HanClintoLib v0.3

[HanClinto]

Announcing the release of HanClintoLib v0.3:

HanClintoLib_v0.3.pbepkg (108k)
Updated April 25th, 2009

There are a number of notable changes and improvements to the library over version 0.2.

• There are five new components (see below for details)
• At Ben's (excellent) suggestion, nearly all previous components have been refactored to use both events and properties for communication with other components. This greatly cleans up the code, and simplifies level file creation.
  
• By popular request, all components are now fully documented with ASDoc.
  

Here is the current summary of included components:

• (New in 0.3!) KeyboardInput: A component that provides an entity with simple and easy access to keyboard inputs, both through local events (using Owner.EventDispatcher) on the KeyUp and KeyDown events, as well as through property references that can be polled to see the up/down state of all major keys. This is one of the coolest additions to 0.3, as it really opens some doors to write no-code games (games composed entirely out of base components, defined in a level file).
  
• (New in 0.3!) RotateOnReference: Rotates its owner entity based on polling a pair of references for clockwise and counter-clockwise control. A building-block component that is useful for both player entities as well as AI.
  
• (New in 0.3!) RotateOnEvent: Same as RotateOnReference, but works from events rather than properties. This may become obsolete, but I want to evaluate its usefulness.
  
• (New in 0.3!) Friction:Friction is a component that can be used to add friction to any property of any other component in the owner entity. Assign a property reference to be updated, and on every tick, the property's value will degrade. Useful for quickly adding basic friction to a game for velocities, rotations, or to add some variation to a score bonus multiplier.
  
• (New in 0.3!) MoveForwardOnReference: Moves its owner entity forward (relative to its rotational heading), based on polling a references for on/off control. A building-block component that is useful for both player entities as well as AI. Similar to the old MoveForwardOnEvent, but utilizes the newly refactored method of properties for communication, rather than events.
  
• MoveForwardOnEvent: A component that listens for an event, and when the event is received, it accelerates the entity along the current rotation heading. This can be used to move an AI forwards when it is locked on target to face its target.
  
• StreamEmitter: A continuous emitter component that is activated when a property reference that goes high, to generate a constant number of entities per second. Great for particle effects like smoke trails, or for use with normal PBE entities for firing bullets, or generating a stream of enemies from a spawn point.
  
• BurstEmitter: An emitter component that can be activated with an event to create a burst of a specified number of entities. Great for little sparks and big explosions.
  
• EmitterBase: A base component from which one can create another emitter subclass. Not terribly useful on its own.
  
• CountdownTimer: A simple component that counts down from the time an entity is created, and when the timer expires, it fires an event. A useful building-block class that can be linked together with a burst emitter (perhaps as a time-bomb, to fire off missiles or a burst of enemies), or a DestroyComponent (to make the entity go away after a period of time, such as to make bullets or particles "fizzle out").
  
• CollideNotifier: A simple component that fires an event when a collision happens. This is nice to use in conjunction with a BurstEmitter to create collision spark effects.
  
• FaceEntity: A component that accepts an entity name as a target, and it rotates itself to point at the target entity. Accepts a parameter to limit the rate at which it can rotate. When it is successfully facing its target, it both fires an event to say that it is facing, and sets a property to indicate that it is facing. When the target has moved out of its direct focus, another event is fired to specify that the lock has been lost, and the Facing property is set to false. This component can be useful for AI turrets (to fire when they are lined up), or to steer AI ships towards a target. This component could also be extended / modified to point towards the user's mouse.
  
• DestroyComponent: A component that listens for an event, and when the event is received, it destroys the entity. This component has the advantage that it delays deletion requests until frames are being processed, allowing the entity to be destroyed from Box2D collision handlers. This component could be used in any number of situations -- from timers to make bullets expire, to destroying an entity on a collision, or listening for when something has taken too much damage. It's meant to be a thin, bare-bones utility component useful for quickly piecing together functional entities.
  

While I one day hope to get HanClintoLib to the point where it would be worthwhile to pay for as a component / starter-kit pack, it is now being offered for free of charge, with no strings attached to use this in your personal or commercial projects. I'm very interested in feedback, and value your suggestions. I'm currently putting together a sample game based on this latest version of the library, and I look forward to showcasing it to you all soon.

Thanks for checking this out, and I appreciate your comments!

--clint

[bengarney]

Hey Clint,

I read over the code. Looks good. My thoughts:

• Not many "inner" comments. You have pretty good coverage of the public API but method bodies and private members are largely uncommented, and in some cases cryptic (like _birthday to store when something started happening).
• Some cryptic public members, like TtlMs and such. Generally a good idea to spell it out, like TimeToLiveMS or even TimeToLiveMilliseconds if you really get into it.
• For the KeyboardInput component, I think you could build on InputMap to make something a little easier to use and maintain. There's a certain brute force charm there but I think you are working way too hard.
• For the Friction component, I like what it does but I think its name is misleading. I thought it was altering a physics property, not causing a value to decay to zero... At least the ASDoc comment for the class could be clarified even if the class itself isn't renamed.
• The components which are split to be both event/reference based are interesting. Personally I bias towards using propertyreferences for most of that stuff (like we discussed), but it'll be interesting to see which of those components people gravitate towards. On the theme of building blocks, have you thought about having a "toggle" component that listens for events and alters a property accordingly?

Great work - I hope my comments are useful!

[yuggaz]

Great work Han,

I will definitely check the components out.

Thanks
-Vu