A to Z Scripting: Anatomy of a script - Revision history

Dragofer at 23:41, 23 December 2020

2020-12-23T23:41:52Z

← Older revision		Revision as of 23:41, 23 December 2020
Line 113:		Line 113:
	*Next article: [[A to Z Scripting: More scripting basics]]		*Next article: [[A to Z Scripting: More scripting basics]]
	*Table of contents: [[A to Z Scripting]]		*Table of contents: [[A to Z Scripting]]

			[[Category:Scripting]]

Dragofer at 19:40, 22 December 2020

2020-12-22T19:40:58Z

← Older revision		Revision as of 19:40, 22 December 2020
Line 86:		Line 86:
	sys.wait(2);		sys.wait(2);
	$camera.activate($player1); //activate a camera to disable player controls		$camera.activate($player1); //activate a camera to disable player controls

	sys.trigger($speaker_narrator); //trigger a speaker with a narrator's voice		sys.trigger($speaker_narrator); //trigger a speaker with a narrator's voice
	sys.wait(10); //narrator is speaking		sys.wait(10); //narrator is speaking

	sys.fadeIn('0 0 0', 2); //fade back in from a black screen over 2s		sys.fadeIn('0 0 0', 2); //fade back in from a black screen over 2s
	$camera.activate($player1); //return player controls as soon as the screen starts fading back in		$camera.activate($player1); //return player controls as soon as the screen starts fading back in

Dragofer at 15:30, 21 December 2020

2020-12-21T15:30:36Z

← Older revision		Revision as of 15:30, 21 December 2020
Line 1:		Line 1:
	~~== Anatomy of a script ==~~

	This section will teach some basic scripting literacy, first by defining a handful essential terms, then picking apart some basic scripts of slightly increasing complexity.		This section will teach some basic scripting literacy, first by defining a handful essential terms, then picking apart some basic scripts of slightly increasing complexity.

	=== Basic terms ===		== Basic terms ==

	{\| class="wikitable"		{\| class="wikitable"
Line 18:		Line 16:
	\|}		\|}

	=== Script events ===		== Script events ==
	==== Example: setOrigin() ====		=== Example: setOrigin() ===
	This is a simple script event, in other words a single command. It teleports player1 (sets his origin) to the position '0 150 0'.		This is a simple script event, in other words a single command. It teleports player1 (sets his origin) to the position '0 150 0'.

Line 40:		Line 38:


	==== Example: wait() ====		=== Example: wait() ===
	This is another basic script event which instructs the script to wait for 3s:		This is another basic script event which instructs the script to wait for 3s:

Line 55:		Line 53:


	=== Scripts ===		== Scripts ==
	==== Example: sending a message to the console ====		=== Example: sending a message to the console ===

	Script events need to be inside a script. The below script is as basic as it gets, containing a single script event:		Script events need to be inside a script. The below script is as basic as it gets, containing a single script event:
Line 81:		Line 79:


	==== Example: simple cutscene ====		=== Example: simple cutscene ===

	void simple_cutscene() //a basic cutscene: fade to black, activate a speaker and fade back in		void simple_cutscene() //a basic cutscene: fade to black, activate a speaker and fade back in

Dragofer at 12:38, 21 December 2020

2020-12-21T12:38:10Z

← Older revision		Revision as of 12:38, 21 December 2020
Line 19:		Line 19:

	=== Script events ===		=== Script events ===
	==== Example: ~~wait~~() ====		==== Example: setOrigin() ====
	This is a ~~very basic~~ script event ~~which instructs~~ the ~~script to wait for 3s:~~		This is a simple script event, in other words a single command. It teleports player1 (sets his origin) to the position '0 150 0'.

	~~sys~~.~~wait~~(3);		$player1.setOrigin('0 150 0');

	Here's a closer look at its components:		Here's a closer look at its components:

	* ~~sys~~.		*$player1.
	** ~~Every~~ script ~~event needs to be used on~~ an entity. ~~Very generic events like "wait" are typically used on sys, which is shorthand for~~ the ~~system entity~~.		** This is the name of the player entity: player1.
			** The $ sign tells the script that this is the name of an entity in the map.
			** The . marks the end of the name.

	* ~~wait~~(3)		*setOrigin('0 150 0')
	** This is the ~~actual~~ script event. Every script event ~~must be accompanied by input brackets, even if they~~'~~re empty~~. ~~In this~~ case, ~~"3"~~ is ~~the input~~.		** This is the script event. It sets the origin of the entity to whatever value you enter into the input brackets.
			** Every new word in a script event's name starts capitalised. Scripting is case-sensitive, so this is an important detail.

	* ;		* ;
Line 36:		Line 39:


	~~==== Example: setOrigin() ====~~
	~~This is another simple script event. It's called on player1 and teleports (sets the origin of) him to the position '0 150 0'.~~

	~~$player1~~.~~setOrigin~~(~~'0 150 0'~~);		==== Example: wait() ====
			This is another basic script event which instructs the script to wait for 3s:

			sys.wait(3);

	* ~~$player1~~.		* sys.
	** ~~Notice~~ the $ sign~~: this means~~ the ~~script engine should look for~~ a ~~specific~~ entity ~~in the game with that~~ name. ~~The player is always called~~ "~~player1~~".		** This is shorthand for the system entity. No $ sign is used here because "sys" is the name of a variable that points to the system entity.
			** You always need to name an entity when you use a script event. Very generic events like "wait" typically use sys.

	*~~setOrigin~~(~~'0 150 0'~~)		* wait(3)
	** ~~Every new word in a~~ script event~~'s name starts capitalised~~. ~~Scripting~~ is ~~case-sensitive~~, ~~so this is an important detail~~.		** This is the actual script event. The input is 3.
			** You always need to include input brackets, leaving them empty if the event doesn't need any input.


Line 52:		Line 58:
	==== Example: sending a message to the console ====		==== Example: sending a message to the console ====

	Script events ~~can't work on their own, they~~ need to be inside a script. The below script is as basic as it gets, containing a single script event:		Script events need to be inside a script. The below script is as basic as it gets, containing a single script event:

	void test_script()		void test_script()
Line 58:		Line 64:
	sys.println("Test message.");		sys.println("Test message.");
	}		}


			* The top line creates a new script called test_script. Note that you don't need to end this line with ; because it's not an instruction.

	* void		* void
	** This defines what type of result the script puts out to other scripts: "void" means nothing while i.e. "float" would mean a number~~. In the large majority of cases you'd use void~~.		** In the large majority of cases, a new script definition begins with void. This defines what type of result the script puts out to other scripts: "void" means nothing while i.e. "float" would mean a number.

	* test_script()		* test_script()
	** This is the name of the script~~: "test_script"~~.		** This is the name of the script followed by mandatory input brackets. In this case they're empty, but for a script that should damage various entities by various amounts you could define an entity input and a float (number) input.
	** Like with script events, ~~input brackets are mandatory~~ for ~~scripts, even if the script doesn't use them. For~~ a script that should damage various entities by various amounts, you could define an entity input and a float (number) input.
	** Note that no semicolon is needed at the end of this top line.

	*{}		*{}
	** Curly brackets mark the ~~body~~ of the script. Script events go here.		** Curly brackets mark the beginning and end of the script itself. Script events go here.

	* sys.println("Test message");		* sys.println("Test message");
	** This is a script event which prints a text to the console and then leaves a line (ln) so that every text is on its own line.		** This is a script event which prints a text ("Test message") to the console and then leaves a line (ln). Leaving a line ensures that every text will be on its own line.


	==== Example: simple cutscene ====		==== Example: simple cutscene ====

	void simple_cutscene()		void simple_cutscene() //a basic cutscene: fade to black, activate a speaker and fade back in
	{		{
	sys.fadeOut('0 0 0', 2); //fade to black (color vector '0 0 0') in 2s		sys.fadeOut('0 0 0', 2); //fade to black (color vector '0 0 0') over 2s
	sys.wait(2); ~~//wait 2s for the fadeOut~~		sys.wait(2);
	$camera.activate($player1); //activate a camera to disable player controls		$camera.activate($player1); //activate a camera to disable player controls
	sys.trigger($speaker_narrator); //trigger a speaker with a narrator's voice
			sys.trigger($speaker_narrator); //trigger a speaker with a narrator's voice
	sys.wait(10); //~~wait while the~~ narrator is speaking		sys.wait(10); //narrator is speaking
	sys.fadeIn('0 0 0', 2); //fade back in from a black screen in 2s
			sys.fadeIn('0 0 0', 2); //fade back in from a black screen over 2s
	$camera.activate($player1); //return player controls as soon as the screen starts fading back in		$camera.activate($player1); //return player controls as soon as the screen starts fading back in
	}		}

	~~This scripts a basic cutscene: fade to black, activate a speaker, fade back in. At both ends a camera is toggled so that the player can't move while the screen is black.~~

	* //		* //
Line 101:		Line 108:

	* $camera.activate($player1);		* $camera.activate($player1);
	** This is an alternative way to trigger, aka activate, an entity. This is needed when you want one entity to be triggered by another entity~~, instead of "sys"~~. In this case, player1 is the activator who activates the camera. Another example would be the player activating a teleporter entity.		** This is an alternative way to trigger, aka activate, an entity. This is needed when you want one entity to be triggered by another entity. In this case, player1 is the activator who activates the camera. Another example would be the player activating a teleporter entity.

Dragofer: Created page with "== Anatomy of a script == This section will teach some basic scripting literacy, first by defining a handful essential terms, then picking apart some basic scripts of slightl..."

2020-12-21T10:00:05Z

Created page with "== Anatomy of a script == This section will teach some basic scripting literacy, first by defining a handful essential terms, then picking apart some basic scripts of slightl..."

New page

== Anatomy of a script ==

This section will teach some basic scripting literacy, first by defining a handful essential terms, then picking apart some basic scripts of slightly increasing complexity.

=== Basic terms ===

{| class="wikitable"
|-
| Script events || For purposes of this guide, a script event is a single action of some kind, i.e. waiting x seconds or triggering an entity. They are the basic building blocks of scripting.
|-
| Script function || For purposes of this guide, a script function is what one thinks of as a "script": a set of instructions. Usually this guide will refer to them simply as "scripts".
|-
| Scriptobject || This is a powerful set of scripts that are assigned to single entities. It allows creating entities with scripted behaviours, i.e. a candle holder that controls the skin, particle, lit state etc. of its candle.
|-
| Variables || Variables store a piece of data, such as an entity's name or a position, which can be modified or used by a script event. They are another basic building block, allowing a script to have variable effects and to store data for later use. Every variable needs to have a name and a data type.
|-
| Data types || This informs the engine whether a piece of data is a text (string), number (float), vector etc. Every variable and every input/output of a script event needs to have a data type.
|}

=== Script events ===
==== Example: wait() ====
This is a very basic script event which instructs the script to wait for 3s:

sys.wait(3);

Here's a closer look at its components:

* sys.
** Every script event needs to be used on an entity. Very generic events like "wait" are typically used on sys, which is shorthand for the system entity.

* wait(3)
** This is the actual script event. Every script event must be accompanied by input brackets, even if they're empty. In this case, "3" is the input.

* ;
** A semicolon is needed to mark the end of a line of instructions. Forgetting these is a common mistake that stops the map from loading.

==== Example: setOrigin() ====
This is another simple script event. It's called on player1 and teleports (sets the origin of) him to the position '0 150 0'.

$player1.setOrigin('0 150 0');

* $player1.
** Notice the $ sign: this means the script engine should look for a specific entity in the game with that name. The player is always called "player1".

*setOrigin('0 150 0')
** Every new word in a script event's name starts capitalised. Scripting is case-sensitive, so this is an important detail.

=== Scripts ===
==== Example: sending a message to the console ====

Script events can't work on their own, they need to be inside a script. The below script is as basic as it gets, containing a single script event:

void test_script()
{
sys.println("Test message.");
}

* void
** This defines what type of result the script puts out to other scripts: "void" means nothing while i.e. "float" would mean a number. In the large majority of cases you'd use void.

* test_script()
** This is the name of the script: "test_script".
** Like with script events, input brackets are mandatory for scripts, even if the script doesn't use them. For a script that should damage various entities by various amounts, you could define an entity input and a float (number) input.
** Note that no semicolon is needed at the end of this top line.

*{}
** Curly brackets mark the body of the script. Script events go here.

* sys.println("Test message");
** This is a script event which prints a text to the console and then leaves a line (ln) so that every text is on its own line.

==== Example: simple cutscene ====

void simple_cutscene()
{
sys.fadeOut('0 0 0', 2); //fade to black (color vector '0 0 0') in 2s
sys.wait(2); //wait 2s for the fadeOut
$camera.activate($player1); //activate a camera to disable player controls
sys.trigger($speaker_narrator); //trigger a speaker with a narrator's voice

sys.wait(10); //wait while the narrator is speaking
sys.fadeIn('0 0 0', 2); //fade back in from a black screen in 2s
$camera.activate($player1); //return player controls as soon as the screen starts fading back in
}

This scripts a basic cutscene: fade to black, activate a speaker, fade back in. At both ends a camera is toggled so that the player can't move while the screen is black.

* //
** This is a comment for the reader: anything behind a double slash gets ignored. This is a useful habit for helping others and your future self understand how your script works.

* sys.fadeOut('0 0 0', 2);
** This script event uses 2 different inputs:
*** '0 0 0' is a vector defining the color to which the screen should fade. Every number represents the intensity of red, green or blue color.
*** 2 is a float (number) defining how long the fadeout should take.

* sys.trigger($speaker_narrator);
** This is a script event to trigger a specific entity called "speaker_narrator", which would simply be a speaker in the map with a custom soundshader.

* $camera.activate($player1);
** This is an alternative way to trigger, aka activate, an entity. This is needed when you want one entity to be triggered by another entity, instead of "sys". In this case, player1 is the activator who activates the camera. Another example would be the player activating a teleporter entity.

== Next / previous article ==

*Next article: [[A to Z Scripting: More scripting basics]]
*Table of contents: [[A to Z Scripting]]