InfoDocumentation is currently sparse. This is a hobby project done in one persons free time, so documentation has taken a back seat to refactoring and feature additions. As the engine nears a potential release candidate, full effort will be put into providing step by step tutorials and documentation. The code base is currently in constant flux so any documentation written now may be obsolete in a week. Documentation is created as objects become finalized. Lack of documentation does not mean lack of existence.
Documentation
Introduction
This thing came about due to entry in dream build play in 2009, written in about one months time to try to meet the deadline. I have since resurrected it and started cleaning/refactoring/new development, with the goal of turning this into an easily customizable engine I can re-use for my own personal projects. I can remember a time when I would have traded anything for a view at peoples attempts at game engines to learn from, so I thought I'd stick my code out in the world in the off chance anyone is curious.
Optimizations I am neglecting any intense optimization (for now) of the engine for the sake of debugging and readability. My philosophy is 'fast enough is good enough for now'. When a significant portion of development is done, or performance is unacceptable, the profiler comes out and optimization can occur. Nobody likes a premature optimizer.
Code Documentation
- Common Data Types
- CGuids Documentation Unavailable
class CGuid: used to identify unique instances of objects throughout the system. They are stored in the GUidGameService in a dictionary of <int,object> to link the Guid.Value (int) to the object instance. Guids can also be given a name, which are stored in GuidGameService in a separate lookup table of <string, guid>, helpful in debugging and linking objects defined in scene files. CGuid lifetimes and ID assignments are handled by the GuidGameService, which uses a pool behind the scenes for guids management. There are only two objects that use guids: Actors and Users, both of which create and manage their own guids. There inst much need to create new guids yourself
Common use:
CGuid guid = CGuid.Create(this); //creates a new guid linked to 'this'
CGuid guid = CGuid.Create(this, name); //creates a new guid linked to 'this' with 'name' in name table
Object o = guid.Resolve(); //gets the object guid is linked too
RandomType type = CGuid.Resolve<T>(); //gets object guid is linked too as type T
CGuid frmScript = CGuid.GetGuid(GuidName); //gets the guid from name table of 'GuidName'
- Actors Documentation Unavailable
interface IActor, used to interface with actor objects of type BaseActor. The Actor object is essentially a container object that contains components which drive all of its behavior. The actor object contains its component list (queriable by type or interace), quick access to game services such as the EventRouter, its assigned CGuid, and control flags that handle the lifetime of the actor object.
Common use of an IActor object:
IActor actor = Scene.CreateEmptyActor();
actor.AttachComponent(new PositionCmp());
IPosition actorsPosition = actor.Get<IPosition>();
Object that is essentially a dressed up Dictionary<String, Object> for use in passing key value airs loaded from definition files to components. This object provides simplified methods of retrieving values, and converting Strings (from script) to the data type requested. Objects start out as String.String pairs, and can be set to be stored back into the object as String,<T> to speed up subsequent calls to retrieve parameters. For example:
myComponent.ScriptableValue = ParameterObject.GetAs<Vector3>("Parameter Name", new Vector3(default value), boolSaveConvertedValue);
Objects that implement the IComponent interface, which implement specific behaviors or properties. These are the workhorse of actor objects. Components contain Initilization() methods, Set() methods that accept the Parameter data type (String/Object pair with type conversion) to work with scripting, Update(elapsedTime) method, Remove() method. Components can be as simple as providing access to a single property (such as position or rotation), a single behavior (ImpulseMover), behavioral control (user input controlling physics bodies), Respond to events (Triggerable/Useable components), raise events (OnDeath component), or even a component dedicated to all aspects of an object (though not recommended!)
Some Examples are:
PositionCmp: The basic position component implements IPosition, which provides access to a Vector2 PositionV2 and Vector3 PositionV3.
CircleBodyCmp: Implements the IFarseerPhysicsBody interface (allows access to Body::Body), and inherites from FarseerPhysicsBodyCmp. Contains a constructor/initialization that creates a circular body in the farseer engine and parsing of parameters from script
ModelCmp: provides access to IGraphic3D interface, IGraphicVisibility interface. Handles drawing a specified Model. Requires objects to have, at minimum, a component that provides IPosition
Events can be raised at any point using the EventRouterGameService. Events contain information about what object raised the event, who the object is from (CGuid), time, type, and an IEventData data property. Events are pooled in the event router, and do not need to be instantiated. The event router handles sending the event to the correctly registered listeners.
EventData is the actual data used for events, which can be created and sent, using the event router. The EventData would be events such as 'PlayerJoin, ButtonPress, ButtonRelease, ActorDied, ActorUse, PlaySound'. EventData are small objects that generally contain one constructor and several properties. Not all events need any data, such as 'EnablePhysicsDebug'.
Sample call: EventRouter.RaiseEvent(this, new PlaySound(SoundName));