ProtoRPG:Actions

Here's the basic about actions :

• Actions are objects.
• They can be used alone are grouped within an array.
• Actions grouped in array can carry a label property for branching
• Each action can return a value, which will be passed on to the next action .
• Actions can also produce a fail condition.
• Processing halts on the first action making a fail, unless the action provided an onFail property, which can give the label a new action to jump.

All action use the following properties :

{	action: "actionName",
	label: "someLabel" // Optional, used for branching to
	onFail: "someOtherLabel" // Optional, label to jump to when failing
}

Generic actions

Usable in all context of the game.

Move

Move the character to a different location.

{	action: "move",
	x: pos_x, y: pos_y, // New x,y coordinates
	map: 'newmap.txt" // Optional, target map (same map if omitted)
}

Fails if map or x,y are incorrect.

Get

Puts one (or several) item(s) into the player inventory.

{	action: "get",
	item: "itemName", // Item code
	qty: 1	// Quantity (optional, default 1). Negative to remove from  inventory.
}

Fails only when qty is negative and inventory is insufficient.

Change specs

Adds or remove points to player's basic specs.

{	action: "specs",
	target: "hit", // hit, mana or xp (experience point)
	delta: "+max"	// Increment/decrement
}

The delta property gives how much has to be added (positive value) or removed (negative value). The string +max is used to increase hit or mana points to the maximum possible, while -max decrease it to 0.

Set Flag

Flags are simple map/key/value data sets stored in the player savegame. They are useful to keep game events persistent as they can be tested.

{	action: 'setflag',
	name: 'flag1',
	value: 1,  // Optional (defaults to 1).
	map: 'map3.txt'      // Optional (defaults to current map).
}

The value property can be a string, an integer or an increment (described as a string such as "+4" or "-2"). In case an increment is used on a non-existing flag, the flag is considered to start at 0.

Never fails.

Read flag

Just read a flag and send the value to the next action.

{	action: 'readflag',
	name: 'flag1',
}

Return flag value (or 0 if flag doesn't exists).

Test flag

This is to be chained with other actions as the actions that follows will only be done if test is passed.

{	action: 'testflag',
	name: 'flag1',
	test: '>',   // Optional (defaults ">"). Only > is supported right now.
	value: 0,     // Optional (defaults 0). Value to test for.
	onFail: 'label1' // Jumps there if test fails.
}

The above object will test if flag "flag1" is above 0 (or if a flag with such a name exists at all).

All flag stored as string are considered to be 1, except empty strings which are 0. Non-existing flags are considered 0.

Fails when condition isn't met (allowing for branching with onFail).

Sound

Play a sound.

{	action: 'sound',
	file: 'sound_sample.wav'
}

This will just play a sound effect (file must be located whithin the sounds directory). Always succeeds (even if the file is missing).

Say

Just show the user a message.

{	action: 'say',
	text: 'Text to show'
	modal: true // Optional (defaults true)
}

The text property can include a #result# keyword that will be matched and replaced with the previous action return value (if any).

If modal is set to false the message just show up on the command window. Otherwise it'll be a modal window that the user has to close manually.

Ask

Ask the player a question (showed as a modal window)

{	action: 'ask',
	text: 'Question text', // Text displayed
	form: 'open', // Optional, can be 'open' (default) or 'choice'
	answers: [{ key: 'yes', value: 'label1'}, { key: '#any', value: 'label2' }] // Optional
}

The text property can include a #result# keyword that will be matched and replaced with the previous action return value (if any).

The form property defines whether the user is presented with an open-ended question (freeform answer, the default) or must choose between a set of possible answers (choice with checkboxes).

answers is an optional property that lets you define which label to jump to (value) depending on what the user answers (key). If this property is omitted, the action will just pass the user answer to the next action.

If the form is open and answers are provided, the user must type exactly the possible answers (user input will be turned in lowercase and stripped from excess spaces before comparing with acceptable answers), unless a #any special answer has been provided (which will act as a catch-all).

Meta actions

Fail

This action just produce a fail, ending processing of a serie of actions.

{	action: 'fail'
}

Tileset actions

Usable for tiles definition within a tileset.

Replace

Replace a tile with another on the map. This is useful for situations such as doors that can be opened, switch-activated secret passage

{	action: 'replace',
	newTile: tile_id 	// New tile ID
	x: tile_x, y: tile_y	// (optional, defaults to tile trigering the event)
}