Saving and Restoring - Revision history

Greebo: Should I save the base class?

2008-06-30T09:35:44Z

Should I save the base class?

@@ Line 200: / Line 200: @@
+  }
 The savefile can be considered as a stream of data. All the classes are saved/restored in the exact same order, otherwise the data gets restored to the wrong class members.
 == Saving Raw Pointers ==

Greebo: /* Call Order */

2008-06-30T09:30:36Z

Call Order

← Older revision		Revision as of 09:30, 30 June 2008
Line 185:		Line 185:

	== Call Order ==		== Call Order ==
	Another important thing to ~~not~~ is the call order in the Save/Restore methods. As an example, suppose you want to save an int, a string and a bool to your savegame:		Another important thing to remember is the call order in the Save/Restore methods. As an example, suppose you want to save an int, a string and a bool to your savegame:
	void myClass::Save(idSaveGame* savefile)		void myClass::Save(idSaveGame* savefile)
	{		{

Greebo: /* Saving idLists */

2008-06-30T09:29:53Z

Saving idLists

← Older revision		Revision as of 09:29, 30 June 2008
Line 280:		Line 280:
	The important thing is to resize the list before starting the for loop, the '''myStringList[i]''' array access must not crash.		The important thing is to resize the list before starting the for loop, the '''myStringList[i]''' array access must not crash.

	{{sdk}} ~~{{tutorial}}~~		{{sdk}} [[Category:Tutorial]]

Greebo: /* Further Notes potentially making your Life easier */

2008-06-30T09:28:53Z

Further Notes potentially making your Life easier

← Older revision		Revision as of 09:28, 30 June 2008
Line 245:		Line 245:
	** each GetEntity() call implicitly checks whether the entity is actually existing, returns NULL if this fails.		** each GetEntity() call implicitly checks whether the entity is actually existing, returns NULL if this fails.
	So basically, the idEntityPtr<idEntity> construct lets you know when the entity has been removed and your code can deal with it, which comes with the cost of the GetEntity() call each time you need to access the contained pointer.		So basically, the idEntityPtr<idEntity> construct lets you know when the entity has been removed and your code can deal with it, which comes with the cost of the GetEntity() call each time you need to access the contained pointer.

			== Dereferencing idEntityPtrs during Restore ==
			As mentioned above, the '''idEntityPtr''' structure doesn't store an actual idEntity* raw pointer, but uses an integer to do so (which is looked up in the entity index in '''gameLocal.entities'''). This integer is resolved as soon as the client calls '''getEntity()'''. It is important that the gameLocal.entities array is initialised by the time the getEntity() method is called, which '''can't be guaranteed when the restore routine is still running'''. The order the entities are restored from the savegame is arbitrary and you therefore can't rely on entity X to be restored and available before entity Y. If you really need to access other entities to fully restore your class, you must work around that by using the Event system. Just post an event with 0 milliseconds delay time which restores the information. By the time the event is fired, all the entities are restored and it's safe to dereference the idEntityPtr. Examples can be found by searching for '''PostEventMS''' in the project:
			PostEventMS(&EV_SetOwnerFromSpawnArgs, 0); // Call the event with 0 msecs delay

	== Saving References ==		== Saving References ==
	As C++ references can't be changed after class construction, so this is an absolute no-no for use in the SDK. Unless you start to use some tricks with reference encapsulation classes, you're lost here. Change your reference to a compatible structure like idEntityPtr or change your class.		As C++ references can't be changed after class construction, so this is an absolute no-no for use in the SDK. Unless you start to use some tricks with reference encapsulation classes, you're lost here. Change your reference to a compatible structure like idEntityPtr or change your class.

	== Saving ~~idList~~ ==		== Saving idLists ==
	I thought it would be handy to have a prototype save/restore routine for idList in this article, so here it goes. Suppose we have a list of strings like this:		I thought it would be handy to have a prototype save/restore routine for idList in this article, so here it goes. Suppose we have a list of strings like this:
	idList<idStr> myStringList;		idList<idStr> myStringList;
Line 276:		Line 280:
	The important thing is to resize the list before starting the for loop, the '''myStringList[i]''' array access must not crash.		The important thing is to resize the list before starting the for loop, the '''myStringList[i]''' array access must not crash.

	~~== Dereferencing idEntityPtrs during Restore ==~~		{{sdk}} {{tutorial}}
	As mentioned above, the '''idEntityPtr''' structure doesn't store an actual idEntity* raw pointer, but uses an integer to do so (which is looked up in the entity index in '''gameLocal.entities'''). This integer is resolved as soon as the client calls '''getEntity()'''. It is important that the gameLocal.entities array is initialised by the time the getEntity() method is called, which '''can't be guaranteed when the restore routine is still running'''. The order the entities are restored from the savegame is arbitrary and you therefore can't rely on entity X to be restored and available before entity Y. If you really need to access other entities to fully restore your class, you must work around that by using the Event system. Just post an event with 0 milliseconds delay time which restores the information. By the time the event is fired, all the entities are restored and it's safe to dereference the idEntityPtr. Examples can be found by searching for '''PostEventMS''' in the project:
	~~PostEventMS(&EV_SetOwnerFromSpawnArgs, 0); // Call the event with 0 msecs delay~~

	{{~~tutorial-~~sdk}}
	{{~~coding-sdk~~}}

Greebo: /* The idEntityPtr template */

2008-06-30T09:27:59Z

The idEntityPtr template

← Older revision		Revision as of 09:27, 30 June 2008
Line 232:		Line 232:
	idEntityPtr<idAI> myAI;		idEntityPtr<idAI> myAI;
	As mentioned above, the idEntityPtr provides a Save/Restore method, so it can be conveniently used. Behind the scenes, only the entity index gets written to the savefile, as you might expect.		As mentioned above, the idEntityPtr provides a Save/Restore method, so it can be conveniently used. Behind the scenes, only the entity index gets written to the savefile, as you might expect.


	== idEntity* vs. idEntityPtr<idEntity> ==		== idEntity* vs. idEntityPtr<idEntity> ==

Greebo: /* Further Notes potentially making your Life easier */

2008-06-30T09:26:10Z

Further Notes potentially making your Life easier

← Older revision		Revision as of 09:26, 30 June 2008
Line 201:		Line 201:
	The savefile can be considered as a stream of data. All the classes are saved/restored in the exact same order, otherwise the data gets restored to the wrong class members.		The savefile can be considered as a stream of data. All the classes are saved/restored in the exact same order, otherwise the data gets restored to the wrong class members.

	== ~~Entity~~ Pointers ==		== Saving Raw Pointers ==
			First rule is: whereever possible, avoid to use raw pointers (except for the example Ishtvan wrote about, using the WriteObject()/ReadObject() method). Pointers can't be saved/restored just like that. Supposed you have some kind of graph which is interconnected by raw pointers and you're in the unlucky situation to save this structure, you can follow some of the general guidelines of graph serialisation: http://www.parashift.com/c++-faq-lite/serialization.html

			== The idEntityPtr<> template ==
	There is a templated container call idEntityPtr: this object wraps around an idEntity* pointer and can be saved/restored just fine. It provides an assignment operator taking idEntity* pointers, which looks up the entity index in the gameLocal.entities[] array. Only this index is saved into the structure (and the savefile). In case you need to access the entity, you call the '''idEntityPtr::getEntity()''' method, see the example below.		There is a templated container call idEntityPtr: this object wraps around an idEntity* pointer and can be saved/restored just fine. It provides an assignment operator taking idEntity* pointers, which looks up the entity index in the gameLocal.entities[] array. Only this index is saved into the structure (and the savefile). In case you need to access the entity, you call the '''idEntityPtr::getEntity()''' method, see the example below.

Line 230:		Line 233:
	As mentioned above, the idEntityPtr provides a Save/Restore method, so it can be conveniently used. Behind the scenes, only the entity index gets written to the savefile, as you might expect.		As mentioned above, the idEntityPtr provides a Save/Restore method, so it can be conveniently used. Behind the scenes, only the entity index gets written to the savefile, as you might expect.

	~~== Saving Raw Pointers ==~~
	First rule is: whereever possible, avoid to use raw pointers (except for the example Ishtvan wrote about, using the WriteObject()/ReadObject() method). Pointers can't be saved/restored just like that. Supposed you have some kind of graph which is interconnected by raw pointers and you're in the unlucky situation to save this structure, you can follow some of the general guidelines of graph serialisation: http://www.parashift.com/c++-faq-lite/serialization.html

	== idEntity* vs. idEntityPtr<idEntity> ==		== idEntity* vs. idEntityPtr<idEntity> ==

Greebo: /* idEntity* vs. idEntityPtr */

2008-06-30T09:22:09Z

idEntity* vs. idEntityPtr

← Older revision		Revision as of 09:22, 30 June 2008
Line 238:		Line 238:
	** raw pointer, is fast when accessing the entity		** raw pointer, is fast when accessing the entity
	** can be saved via ReadObject/WriteObject		** can be saved via ReadObject/WriteObject
	** can be broken when the entity is removed from the game (you won't know until the game ~~crashes~~)		** can be broken when the entity is removed from the game (you won't know until your code crashes the game when trying to access it)
	* '''idEntityPtr<idEntity>'''		* '''idEntityPtr<idEntity>'''
	** stores the spawnid internally		** stores the spawnid internally

Greebo: idEntity* vs. idEntityPtr

2008-06-30T09:21:37Z

idEntity* vs. idEntityPtr<idEntity>

@@ Line 232: / Line 232: @@
 == Saving Raw Pointers ==
 First rule is: whereever possible, avoid to use raw pointers (except for the example Ishtvan wrote about, using the WriteObject()/ReadObject() method). Pointers can't be saved/restored just like that. Supposed you have some kind of graph which is interconnected by raw pointers and you're in the unlucky situation to save this structure, you can follow some of the general guidelines of graph serialisation: http://www.parashift.com/c++-faq-lite/serialization.html
 == Saving References ==

Greebo at 07:36, 11 October 2007

2007-10-11T07:36:21Z

← Older revision		Revision as of 07:36, 11 October 2007
Line 266:		Line 266:
	As mentioned above, the '''idEntityPtr''' structure doesn't store an actual idEntity* raw pointer, but uses an integer to do so (which is looked up in the entity index in '''gameLocal.entities'''). This integer is resolved as soon as the client calls '''getEntity()'''. It is important that the gameLocal.entities array is initialised by the time the getEntity() method is called, which '''can't be guaranteed when the restore routine is still running'''. The order the entities are restored from the savegame is arbitrary and you therefore can't rely on entity X to be restored and available before entity Y. If you really need to access other entities to fully restore your class, you must work around that by using the Event system. Just post an event with 0 milliseconds delay time which restores the information. By the time the event is fired, all the entities are restored and it's safe to dereference the idEntityPtr. Examples can be found by searching for '''PostEventMS''' in the project:		As mentioned above, the '''idEntityPtr''' structure doesn't store an actual idEntity* raw pointer, but uses an integer to do so (which is looked up in the entity index in '''gameLocal.entities'''). This integer is resolved as soon as the client calls '''getEntity()'''. It is important that the gameLocal.entities array is initialised by the time the getEntity() method is called, which '''can't be guaranteed when the restore routine is still running'''. The order the entities are restored from the savegame is arbitrary and you therefore can't rely on entity X to be restored and available before entity Y. If you really need to access other entities to fully restore your class, you must work around that by using the Event system. Just post an event with 0 milliseconds delay time which restores the information. By the time the event is fired, all the entities are restored and it's safe to dereference the idEntityPtr. Examples can be found by searching for '''PostEventMS''' in the project:
	PostEventMS(&EV_SetOwnerFromSpawnArgs, 0); // Call the event with 0 msecs delay		PostEventMS(&EV_SetOwnerFromSpawnArgs, 0); // Call the event with 0 msecs delay

			{{tutorial-sdk}}
			{{coding-sdk}}

Greebo: /* Further Notes potentially making your Life easier */

2007-10-11T07:34:40Z

Further Notes potentially making your Life easier

← Older revision		Revision as of 07:34, 11 October 2007
Line 179:		Line 179:
	= Further Notes potentially making your Life easier =		= Further Notes potentially making your Life easier =
	''written by greebo''		''written by greebo''

	When traversing the SDK to make the Saving/Loading routines working again with our Mod code, I noticed a few things. I better write them here to prevent other people from running into the same situation.		When traversing the SDK to make the Saving/Loading routines working again with our Mod code, I noticed a few things. I better write them here to prevent other people from running into the same situation.
	== Data Types that can be saved/restored ==		== Data Types that can be saved/restored ==
Line 207:		Line 208:
	// This wraps around a idEntity* pointer		// This wraps around a idEntity* pointer
	idEntityPtr<idEntity> myEnemy;		idEntityPtr<idEntity> myEnemy;

	public:		public:

	void setEnemy(idEntity* newEnemy)		void setEnemy(idEntity* newEnemy)
	{		{