checkpoint

Module(s): vncanvas-base, vncanvas-chkpt
Description: Marks a position in the script as a checkpoint for saving/loading.

Also supports named checkpoints by setting gameNamedCheckpts in Config file (unset/false by default).
By using named checkpoints, the game developer can specify which checkpoint to load. This is useful for example when a player, upon reaching a bad ending, is allowed to return to a specific location in the plot, to redo the story and make different choices.
However, due to its nature, named checkpoints are not compatible with previous checkpoint saves.
Note also that local storage is not unlimited, and using multiple checkpoints will cause localStorage usage to increase. So use named checkpoints efficiently and sparingly. Whenever possible, use clear to delete a checkpoint.

Syntax

checkpoint, "save"	Saves the game at the current checkpoint.
checkpoint, "load"	Loads a previously saved checkpoint. Should only be used at start of game.
checkpoint, {param}	Perform action on named checkpoint. Only if gameNamedCheckpts is set in Config file. Parameters are given as {param:value, param:value, ...}

Parameter Summary

Parameter	Attributes and Description
load:"checkpt_name" save:"checkpt_name" clear:"checkpt_name"	Use only if gameNamedCheckpts is set checkpt_name is the checkpoint id. LOAD loads a previously set checkpoint of the given name. SAVE saves the current game at the specified checkpoint. CLEAR clears the given checkpoint. Note: Even though there's no code difference between a named and an unnamed checkpoint load, their intended use is different. An unnamed checkpoint is usually for loading/continuing at the start of the game, so the game is practically starting without resources loaded or variables set. However, a named checkpoint may be loaded somewhere down the line. At this point, there may be resources loaded or variables set. If not handled properly, references to these resources may be lost when the named checkpoint is loaded, and at the worst case, may result in memory leakage. A manual resource management is recommended prior to loading the named checkpoint.

Parameter

Attributes and Description

load:"checkpt_name"

save:"checkpt_name"

clear:"checkpt_name"

Use only if gameNamedCheckpts is set

checkpt_name is the checkpoint id.
LOAD loads a previously set checkpoint of the given name.
SAVE saves the current game at the specified checkpoint.
CLEAR clears the given checkpoint.

Note: Even though there's no code difference between a named and an unnamed checkpoint load, their intended use is different.
An unnamed checkpoint is usually for loading/continuing at the start of the game, so the game is practically starting without resources loaded or variables set.
However, a named checkpoint may be loaded somewhere down the line. At this point, there may be resources loaded or variables set. If not handled properly, references to these resources may be lost when the named checkpoint is loaded, and at the worst case, may result in memory leakage. A manual resource management is recommended prior to loading the named checkpoint.

Example

The game is automatically saved at the checkpoint. Note: "save" is a predefined parameter.

  
chapter = [
	/* As a requirement for saves, we need to use a label to
	identify the script; in this case, we use a "chapter" label
	as the first keyword-value pair (which is same as the object
	name). However, it is good practice to label all script chapters. */
	label, "chapter",

	...
	checkpoint, "save",
	...
	
];

A new game is started or a saved game is loaded using "menu". Note: "load" is a predefined parameter.

  
chapter = [
	label, "chapter",

	...
	menu, [ "",
			"Start a new game", "label1",
			"Continue game", "label2" ],
			
	label, "label2",
	checkpoint, "load",
	/* Note, "load" automatically jumps to saved checkpoint */
	
	label, "label1",
	/* Start a new game here */
	...
	
];

The game creates a named checkpoint "go_back_here", then loads or clear the checkpoint depending on which branch of the story the player followed.

  
chapter = [
	label, "chapter",
	...
	checkpoint, {save:"go_back_here"},
	...
	/* game forks here between good_choice and bad_choice */
	...
	label: "bad_choice",
	/* allow the player to return */
	/* unload resources not needed here */
	checkpoint, {load:"go_back_here"},
	...
	label: "good_choice",
	/* checkpoint is no longer needed */
	checkpoint, {clear:"go_back_here"},
	...
];