Added standard overview/usage comments to the entity files.

This was SVN commit r248.

source/simulation/BaseEntity.h

@@ -1,3 +1,20 @@
+// BaseEntity.h
+//
+// Last modified: 22 May 04, Mark Thompson mot20@cam.ac.uk / mark@wildfiregames.com
+// 
+// Entity Templates
+//
+// Usage: These templates are used as the default values for entity properties.
+//        Due to Prometheus' data-inheritance model for these properties,
+//			 templates specify a base-template, then override only those properties
+//			 in that template that need to change.
+//        Similarly, entities need only specify properties they possess that are
+//           different to the ones in their respective templates. Of course,
+//           properties such as position, current HP, etc. cannot be inherited from
+//           a template in this way.
+//
+//        Note: Data-inheritance is not currently implemented.
+
 #ifndef BASE_ENTITY_INCLUDED
 #define BASE_ENTITY_INCLUDED
 

source/simulation/BaseEntityCollection.h

@@ -1,4 +1,19 @@
-// Last modified: May 15 2004, Mark Thompson (mark@wildfiregames.com)
+// BaseEntityCollection.h
+//
+// Last modified: 22 May 04, Mark Thompson mot20@cam.ac.uk / mark@wildfiregames.com
+// 
+// Keeps tabs on the various types of entity that roam the world.
+//
+// General note: Template, Base Entity, and Entity Class are used more-or-less interchangably.
+// 
+// Usage: g_EntityTemplateCollection.loadTemplates(): initializes the lists from mods/official/entities/templates
+//        After that, you can:
+//			Find an entity class by the actor it uses: g_EntityTemplateCollection.getTemplateByActor()
+//				Note that this is included solely for loading ScnEd 4,5 and 6 format map files. Don't rely on this
+//				working all the time.
+//	        Find an entity class by it's name: g_EntityTemplateCollection.getTemplate()
+//		  g_EntityManager will also use this class to lookup entity templates when you instantiate an entity with 
+//			a class name string.
 
 #ifndef BASEENT_COLLECTION_INCLUDED
 #define BASEENT_COLLECTION_INCLUDED

source/simulation/Entity.h

@@ -1,4 +1,24 @@
-// Last modified: May 15 2004, Mark Thompson (mark@wildfiregames.com)
+// Entity.h
+//
+// Last modified: 22 May 04, Mark Thompson mot20@cam.ac.uk / mark@wildfiregames.com
+// 
+// Entity class.
+//
+// Usage: Do not attempt to instantiate this class directly. (See EntityManager.h)
+//		  Most of the members are trivially obvious; some highlights are:
+//
+//			HEntity me: is a reference to this entity. Use instead of the address-of operator for
+//						non-temporary references. See EntityHandles.h
+//						When an entity dies, this should be set to refer to the bad-handle handle.
+//			CUnit* m_actor: is the visible representation of this entity.
+//			std::hash_map m_properties: isn't yet used, is capable of storing properties defined by script.
+//			
+//			snapToGround(): Called every frame, this will ensure the entity never takes flight.
+//			updateActorTransforms(): Must be called every time the position of this entity changes.
+//
+//			Some notes: update() and dispatch() /can/ be called directly without ill effects,
+//						but it's preferable to go through the Entity manager and the Scheduler, respectively.
+//
 
 #ifndef ENTITY_INCLUDED
 #define ENTITY_INCLUDED
@@ -36,6 +56,7 @@ public:
 
 	std::hash_map<CStr,CGenericProperty,CStr_hash_compare> m_properties;
 
+private:
 	CEntity( CBaseEntity* base, CVector3D position, float orientation );
 public:
 
@@ -49,6 +70,4 @@ public:
 	void pushOrder( CEntityOrder& order );
 };
 
-extern void PASAPScenario();
-
 #endif

source/simulation/EntityHandles.h

@@ -1,3 +1,22 @@
+// EntityHandles.h
+//
+// Last modified: 22 May 04, Mark Thompson mot20@cam.ac.uk / mark@wildfiregames.com
+// 
+// Entity smart pointer definitions.
+//
+// Usage: Use in place of a standard CEntity pointer.
+//	      Handles dereference and pointer-to-member as a standard smart pointer.
+//		  Reference counted. Handles are freed and entity classes released when refcount hits 0.
+//		  For this reason, be careful where and how long you store these.
+//        
+//		  Entities maintain their own handles via their HEntity me member.
+//		  To release an entity, scramble this handle. The memory will be freed when the last reference to it expires.
+//
+//        Standard CEntity pointers must not be used for a) anything that could be sent over the network.
+//														 b) anything that will be kept between simulation steps.
+//		  CEntity pointers will be faster for passing to the graphics subsytem, etc. where they won't be stored.
+//		  And yes, most of this /is/ obvious. But it should be said anyway.
+
 #ifndef ENTITY_HANDLE_INCLUDED
 #define ENTITY_HANDLE_INCLUDED
 

source/simulation/EntityManager.h

@@ -1,3 +1,17 @@
+// EntityManager.h
+//
+// Last modified: 22 May 04, Mark Thompson mot20@cam.ac.uk / mark@wildfiregames.com
+// 
+// Maintains entity id->object mappings. Does most of the work involved in creating an entity.
+//
+// Usage: Do not attempt to directly instantiate an entity class.
+//        HEntity bob = g_EntityManager.create( unit_class_name, position, orientation );
+//	   or HEntity jim = g_EntityManager.create( pointer_to_unit_class, position, orientation );
+//
+//        Perform updates on all world entities by g_EntityManager.updateAll( timestep )
+//		  Dispatch an identical message to all world entities by g_EntityManager.dispatchAll( message_pointer )
+//		  Get an STL vector container of all entities with a certain property with g_EntityManager.matches( predicate )
+
 #ifndef ENTITY_MANAGER_INCLUDED
 #define ENTITY_MANAGER_INCLUDED
 

source/simulation/EntityMessage.h

@@ -1,4 +1,16 @@
-// Message structure
+// EntityMessage.h
+//
+// Last modified: 22 May 04, Mark Thompson mot20@cam.ac.uk / mark@wildfiregames.com
+// 
+// Entity message structure.
+//
+// Usage: Currently, does not support any data to be included with messages.
+//		  Message types are currently: EMSG_TICK: Unused.
+//									   EMSG_INIT: When a new entity is instantiated.
+//												  At map loading, do not issue this message immediately
+//												  for each entity as it is loaded; instead, wait for all
+//												  entities to be created, then issue this message to all
+//												  of them simultaneously.
 
 #ifndef MESSAGING_INCLUDED
 #define MESSAGING_INCLUDED

source/simulation/EntityOrders.h

@@ -1,4 +1,24 @@
-// Last modified: May 15 2004, Mark Thompson (mark@wildfiregames.com)
+// EntityOrders.h
+//
+// Last modified: 22 May 04, Mark Thompson mot20@cam.ac.uk / mark@wildfiregames.com
+// 
+// Entity orders structure.
+//
+// Usage: All orders at this point use the location component of the union.
+//		  Orders are: ORDER_GOTO_NOPATHING: Attempts to reach the given destination via a line-of-sight
+//											system. Do not create an order of this type directly; it is
+//											used to return a path of line segments from the pathfinder.
+//					  ORDER_GOTO:			Attempts to reach the given destination. Uses the pathfinder
+//											to... er... find the path.
+//											Create this order when a standard movement or movement waypoint
+//											order is required.
+//					  ORDER_PATROL:			As ORDER_GOTO, but pushes the patrol order onto the back of the
+//											order queue after it's executed. In this way, the entity will
+//											circle round a list of patrol points.
+//											Create this order when a standard patrol order is required.
+//
+//		  Entities which exhaust all orders from their queue go to idle status; there is no specific order
+//			  type for this status.
 
 #ifndef ENTITY_ORDER_INCLUDED
 #define ENTITY_ORDER_INCLUDED

source/simulation/EntityProperties.h

@@ -1,3 +1,12 @@
+// EntityProperties.h
+//
+// Last modified: 22 May 04, Mark Thompson mot20@cam.ac.uk / mark@wildfiregames.com
+// 
+// Extended properties table, primarily intended for data-inheritable properties and those defined by JavaScript functions.
+//
+// Usage: Nothing yet.
+//        These properties will be accessed via functions in CEntity/CBaseEntity
+//
 // Inefficiency warning.
 // Will move frequently accessed properties (position, name, etc.) to native C++ primitives.
 // Just playing around with this idea, will probably keep it for at least some of the more exotic and/or user-defined properties.