Osiris Design Patterns - Revision history

Tinkerer: /* Check Whether a Database Is Empty */

2018-10-13T08:41:20Z

Check Whether a Database Is Empty

← Older revision		Revision as of 08:41, 13 October 2018
Line 187:		Line 187:
	...		...

	You cannot specify names for the parameters of ~~```~~DB_Check()~~```~~ in this case. The reason is that this condition can only succeed if ~~```~~DB_Check()~~```~~ is empty. Hence, if you would specify names for the database fields and then use those names in subsequent conditions or actions, they would not be bound to any value at that point.		You cannot specify names for the parameters of '''DB_Check()''' in this case. The reason is that this condition can only succeed if '''DB_Check()''' is empty. Hence, if you would specify names for the database fields and then use those names in subsequent conditions or actions, they would not be bound to any value at that point.

	[[Category:Osiris]]		[[Category:Osiris]]

Tinkerer: /* Game Events */

2018-10-13T08:38:20Z

Game Events

← Older revision		Revision as of 08:38, 13 October 2018
Line 44:		Line 44:
	Two events exist in this category.		Two events exist in this category.
	; [[Osiris/API/GameEventSet\|GameEventSet]] : This event also existed in DOS1. As the documentation page mentions, it is only called with one particular parameter at this time.		; [[Osiris/API/GameEventSet\|GameEventSet]] : This event also existed in DOS1. As the documentation page mentions, it is only called with one particular parameter at this time.
	; [[Osiris/API/GameModeStarted\|GameModeStarted]] : This event is new in DOS2. It is thrown right after the previous one. Its parameter indicates whether the game has been started in campaign (adventure/~~store~~), game master, or arena mode. You can use this to only initialise parts of story that are relevant to the selected mode, by making all goals children of a goal that only completes if the desired game mode started. As of DOS2 Patch 6, all story goals distributed with the main game use this functionality to prevent interference with mods that can be used with more than one game mode.		; [[Osiris/API/GameModeStarted\|GameModeStarted]] : This event is new in DOS2. It is thrown right after the previous one. Its parameter indicates whether the game has been started in campaign (adventure/story), game master, or arena mode. You can use this to only initialise parts of story that are relevant to the selected mode, by making all goals children of a goal that only completes if the desired game mode started. As of DOS2 Patch 6, all story goals distributed with the main game use this functionality to prevent interference with mods that can be used with more than one game mode.

	== Level Events ==		== Level Events ==

Tinkerer: /* Direct Dependencies */

2018-10-13T08:36:23Z

Direct Dependencies

← Older revision		Revision as of 08:36, 13 October 2018
Line 21:		Line 21:
	If you call PROCs from your INIT code, ensure that these are defined in goals that are guaranteed to already have been intialised. You will '''''not''''' get a compile-time nor run-time error if you call a routine declared in a goal that is not yet active; the call will simply not do anything.		If you call PROCs from your INIT code, ensure that these are defined in goals that are guaranteed to already have been intialised. You will '''''not''''' get a compile-time nor run-time error if you call a routine declared in a goal that is not yet active; the call will simply not do anything.

	Example: consider the screenshot of the [[Osiris_Overview#Goal_Initialisation_and_Completion\|Goal Initialisation and Completion]] section. Calling a PROC defined in the ''FTJ_Origins_Ifan'' goal from the INIT code (or from a PROC called from the INIT code) of the ''~~AtaractionArtifacts~~'' goal will silently fail here. The reason is that both goals are subgoals of the ''_Start'' goal, and goals are initialised and activated in alphabetical order. So when the ''~~AtaractionArtifacts~~'' goal gets initialsed, the ''FTJ_Origins_Ifan'' goal is not yet active.		Example: consider the screenshot of the [[Osiris_Overview#Goal_Initialisation_and_Completion\|Goal Initialisation and Completion]] section. Calling a PROC defined in the ''FTJ_Origins_Ifan'' goal from the INIT code (or from a PROC called from the INIT code) of the ''AtaraxianArtifacts'' goal will silently fail here. The reason is that both goals are subgoals of the ''_Start'' goal, and goals are initialised and activated in alphabetical order. So when the ''AtaraxianArtifacts'' goal gets initialsed, the ''FTJ_Origins_Ifan'' goal is not yet active.

	=== Indirect Dependencies ===		=== Indirect Dependencies ===

Tinkerer: Check Whether a Database Is Empty

2018-09-05T11:13:29Z

Check Whether a Database Is Empty

← Older revision		Revision as of 11:13, 5 September 2018
Line 177:		Line 177:

	If a '''DB_EnableCrime()''' fact is added somewhere, we enable the crime and also define a '''DB_CrimeEnabled()''' fact. Next, our second rule ensures that if the original '''DB_EnableCrime()''' fact gets undefined, will will disable the crime the again. We then also undefine the '''DB_CrimeEnabled()''' fact so that we can detect changes again should the '''DB_EnableCrime()''' fact be redefined later.		If a '''DB_EnableCrime()''' fact is added somewhere, we enable the crime and also define a '''DB_CrimeEnabled()''' fact. Next, our second rule ensures that if the original '''DB_EnableCrime()''' fact gets undefined, will will disable the crime the again. We then also undefine the '''DB_CrimeEnabled()''' fact so that we can detect changes again should the '''DB_EnableCrime()''' fact be redefined later.

			= Check Whether a Database Is Empty =

			IF
			CharacterDied(_Char)
			AND
			NOT DB_Check(_, _)
			THEN
			...

			You cannot specify names for the parameters of ```DB_Check()``` in this case. The reason is that this condition can only succeed if ```DB_Check()``` is empty. Hence, if you would specify names for the database fields and then use those names in subsequent conditions or actions, they would not be bound to any value at that point.

	[[Category:Osiris]]		[[Category:Osiris]]

Tinkerer: Creating a rule that triggers on removing a database fact

2018-06-23T17:44:47Z

Creating a rule that triggers on removing a database fact

← Older revision		Revision as of 17:44, 23 June 2018
Line 150:		Line 150:

	The query will only succeed if that DB is not yet defined. When it succeeds, it defines the DB so that future invocations of this query will fail.		The query will only succeed if that DB is not yet defined. When it succeeds, it defines the DB so that future invocations of this query will fail.

			= Trigger On Deleting a Database Fact =

			You cannot simply check on '''DB_CHECK(1)''' getting unset, as the following is invalid code:

			IF
			NOT DB_CHECK(1)
			THEN
			..

			Events only fire when DBs get defined, not when they get removed. However, due to the fact that the database checks that are part of a [[Osiris_Overview#Trigger_Conditions\|rule trigger condition]] can be fulfilled in any order, you can create a rule that triggers on delete a database fact by using a helper:

			IF
			DB_EnableCrime(_Player,_Crime)
			THEN
			DB_CrimeEnabled(_Player,_Crime);
			EnableCrime(_Player,_Crime);

			IF
			DB_CrimeEnabled(_Player,_Crime)
			AND
			NOT DB_EnableCrime(_Player,_Crime)
			THEN
			NOT DB_CrimeEnabled(_Player,_Crime);
			DisableCrime(_Player,_Crime);

			If a '''DB_EnableCrime()''' fact is added somewhere, we enable the crime and also define a '''DB_CrimeEnabled()''' fact. Next, our second rule ensures that if the original '''DB_EnableCrime()''' fact gets undefined, will will disable the crime the again. We then also undefine the '''DB_CrimeEnabled()''' fact so that we can detect changes again should the '''DB_EnableCrime()''' fact be redefined later.

	[[Category:Osiris]]		[[Category:Osiris]]

Tinkerer: /* Game Events */

2018-01-14T14:47:12Z

Game Events

← Older revision		Revision as of 14:47, 14 January 2018
Line 40:		Line 40:

	== Game Events ==		== Game Events ==
			These events are thrown when the game engine has finished initialising, but before any level has been loaded. This means that even global objects are not accessible at this point, and many Osiris calls and queries will fail because the necessary context is missing. The main purpose of these events is to allow for generic story initialisation.

			Two events exist in this category.
			; [[Osiris/API/GameEventSet\|GameEventSet]] : This event also existed in DOS1. As the documentation page mentions, it is only called with one particular parameter at this time.
			; [[Osiris/API/GameModeStarted\|GameModeStarted]] : This event is new in DOS2. It is thrown right after the previous one. Its parameter indicates whether the game has been started in campaign (adventure/store), game master, or arena mode. You can use this to only initialise parts of story that are relevant to the selected mode, by making all goals children of a goal that only completes if the desired game mode started. As of DOS2 Patch 6, all story goals distributed with the main game use this functionality to prevent interference with mods that can be used with more than one game mode.

	== Level Events ==		== Level Events ==

Tinkerer: /* Breaking off a Loop */

2018-01-12T10:48:09Z

Breaking off a Loop

← Older revision		Revision as of 10:48, 12 January 2018
Line 82:		Line 82:
	CharacterSetReactionPriority(_chicken,"DefaultWanderInTrigger",0);		CharacterSetReactionPriority(_chicken,"DefaultWanderInTrigger",0);

			// Very important: ensure we will loop again next time this proc is called!
	PROC		PROC
	Proc_RC_DW_VC_SetNewBroodChicken()		Proc_RC_DW_VC_SetNewBroodChicken()

Tinkerer: /* Factoring Out Checks to Queries */

2017-12-31T13:18:49Z

Factoring Out Checks to Queries

← Older revision		Revision as of 13:18, 31 December 2017
Line 105:		Line 105:

	=== Factoring Out Checks to Queries ===		=== Factoring Out Checks to Queries ===
	Queries offer an easy way to factor out searching logic and the associated ~~book keeping~~ from a proc. For example, we could rewrite the above using a query as follows:		Queries offer an easy way to factor out searching logic and the associated bookkeeping from a proc. For example, we could rewrite the above using a query as follows:

	QRY		QRY

Tinkerer: /* Breaking off a Loop */

2017-12-31T13:18:17Z

Breaking off a Loop

← Older revision		Revision as of 13:18, 31 December 2017
Line 58:		Line 58:
	In many cases you will find yourself iterating a database checking for a condition to be fulfilled, and executing certain actions when this is the case. Often, these actions should only be executed once, for the first fact that fullfills to the conditions. For example, take this slightly simplified code from the Peeper quest, whereby we look for a chicken to hatch the Peeper egg:		In many cases you will find yourself iterating a database checking for a condition to be fulfilled, and executing certain actions when this is the case. Often, these actions should only be executed once, for the first fact that fullfills to the conditions. For example, take this slightly simplified code from the Peeper quest, whereby we look for a chicken to hatch the Peeper egg:

	DB_RC_DW_VC_Chickens((CHARACTERGUID)S_RC_DW_VC_Chicken_001_9053f0be-7d06-4e88-ab20-f411e2e790d0,"RC_DW_VC_Chicken1","RC_DW_VC_AD_Chicken1",0,(TRIGGERGUID)S_RC_DW_VC_Chicken01_DeadTrigger_51b9f0bc-04bf-4f68-~~9e0~~		DB_RC_DW_VC_Chickens((CHARACTERGUID)S_RC_DW_VC_Chicken_001_9053f0be-7d06-4e88-ab20-f411e2e790d0,"RC_DW_VC_Chicken1","RC_DW_VC_AD_Chicken1",0,(TRIGGERGUID)S_RC_DW_VC_Chicken01_DeadTrigger_51b9f0bc-04bf-4f68-9e0d-43058d4a4580); // The 0 means "currently hatching an egg"
	d-43058d4a4580); //~~Last int is if sitting on~~ egg
	DB_RC_DW_VC_Chickens(S_RC_DW_VC_Chicken_002_d8699c1d-3ca1-444b-b985-95de1dc8c708,"RC_DW_VC_Chicken2","RC_DW_VC_AD_Chicken2",0,S_RC_DW_VC_Chicken02_DeadTrigger_629dcb32-e251-48b8-8a33-e710dda8c3fc);		DB_RC_DW_VC_Chickens(S_RC_DW_VC_Chicken_002_d8699c1d-3ca1-444b-b985-95de1dc8c708,"RC_DW_VC_Chicken2","RC_DW_VC_AD_Chicken2",0,S_RC_DW_VC_Chicken02_DeadTrigger_629dcb32-e251-48b8-8a33-e710dda8c3fc);
	DB_RC_DW_VC_Chickens(S_RC_DW_VC_Chicken_003_bcd34f89-8ff2-4d94-8c30-fe09bdbc1163,"RC_DW_VC_Chicken3","RC_DW_VC_AD_Chicken3",0,S_RC_DW_VC_Chicken03_DeadTrigger_72400c76-d222-4996-bef1-b787f449fcc2);		DB_RC_DW_VC_Chickens(S_RC_DW_VC_Chicken_003_bcd34f89-8ff2-4d94-8c30-fe09bdbc1163,"RC_DW_VC_Chicken3","RC_DW_VC_AD_Chicken3",0,S_RC_DW_VC_Chicken03_DeadTrigger_72400c76-d222-4996-bef1-b787f449fcc2);

Tinkerer: Patterns: do something once

2017-10-12T19:52:11Z

Patterns: do something once

← Older revision		Revision as of 19:52, 12 October 2017
Line 47:		Line 47:

	The difference between these two events is explained on the linked pages. Also note that these events are thrown when loading a savegame (for the level in which the game was saved), so do not tie them to rules that should be executed exactly once without adding safeguards. One way is to catch this event in a top-level goal that is then immediately completed as explained in the [[Osiris_Design_Patterns#Program_Initialisation\|Program Initialisation]] section. All one-time initialisation can then be done in the INIT sections of the child goals.		The difference between these two events is explained on the linked pages. Also note that these events are thrown when loading a savegame (for the level in which the game was saved), so do not tie them to rules that should be executed exactly once without adding safeguards. One way is to catch this event in a top-level goal that is then immediately completed as explained in the [[Osiris_Design_Patterns#Program_Initialisation\|Program Initialisation]] section. All one-time initialisation can then be done in the INIT sections of the child goals.


			= Doing Something Once =
			The event-based nature of Osiris makes it easy to consistently perform actions whenever something happens, but sometimes things should happen only once. Several patterns can be used on this depending on the situation.

			== Goal-Based Initialisation ==
			When a goal becomes active, all of the actions in its INIT section are executed. So you can make it a subgoal of another goal that completes when this initialiation should occur, like with the [[#Program Initialisation\|Program Initialisation]] above.

			== Breaking off a Loop ==
			In many cases you will find yourself iterating a database checking for a condition to be fulfilled, and executing certain actions when this is the case. Often, these actions should only be executed once, for the first fact that fullfills to the conditions. For example, take this slightly simplified code from the Peeper quest, whereby we look for a chicken to hatch the Peeper egg:

			DB_RC_DW_VC_Chickens((CHARACTERGUID)S_RC_DW_VC_Chicken_001_9053f0be-7d06-4e88-ab20-f411e2e790d0,"RC_DW_VC_Chicken1","RC_DW_VC_AD_Chicken1",0,(TRIGGERGUID)S_RC_DW_VC_Chicken01_DeadTrigger_51b9f0bc-04bf-4f68-9e0
			d-43058d4a4580); //Last int is if sitting on egg
			DB_RC_DW_VC_Chickens(S_RC_DW_VC_Chicken_002_d8699c1d-3ca1-444b-b985-95de1dc8c708,"RC_DW_VC_Chicken2","RC_DW_VC_AD_Chicken2",0,S_RC_DW_VC_Chicken02_DeadTrigger_629dcb32-e251-48b8-8a33-e710dda8c3fc);
			DB_RC_DW_VC_Chickens(S_RC_DW_VC_Chicken_003_bcd34f89-8ff2-4d94-8c30-fe09bdbc1163,"RC_DW_VC_Chicken3","RC_DW_VC_AD_Chicken3",0,S_RC_DW_VC_Chicken03_DeadTrigger_72400c76-d222-4996-bef1-b787f449fcc2);
			DB_RC_DW_VC_Chickens(S_RC_DW_VC_Chicken_004_66188471-2b54-4f53-8efa-8278125e2c60,"RC_DW_VC_Chicken4","RC_DW_VC_AD_Chicken4",0,S_RC_DW_VC_Chicken04_DeadTrigger_7d824686-06ce-472c-a4ce-cd85300f57b6);
			DB_RC_DW_VC_Chickens(S_RC_DW_VC_Chicken_Scared_81ef9840-7b6e-4d3d-9b60-4c7ed7a286a7,"RC_DW_VC_ChickenScared","RC_DW_VC_AD_ChickenScared",0,S_RC_DW_VC_ScaredChicken_DeadTrigger_65e32575-6cd8-44dc-9af3-ded6982d0

			..

			PROC
			Proc_RC_DW_VC_SetNewBroodChicken()
			AND
			DB_RC_DW_VC_Chickens(_chicken,_dialog,_ad,0,_trigger)
			AND
			CharacterIsDead((CHARACTERGUID)_chicken,0)
			AND
			NOT DB_RC_DW_VC_DoneOnce(1)
			THEN
			DB_RC_DW_VC_DoneOnce(1);
			NOT DB_RC_DW_VC_Chickens(_chicken,_dialog,_ad,0,_trigger);
			DB_RC_DW_VC_Chickens(_chicken,_dialog,_ad,1,_trigger);
			DB_RC_DW_VC_DroppingEgg(_chicken,"0_GoingToEggAsNewHatchingChicken");
			ProcCharacterMoveTo(_chicken,TRIGGERGUID_S_RC_DW_VC_HelplessEggLocation_92d4c501-c342-4e25-b08e-32fb7d396ee9,0,"RC_DW_VC_ChickenWalkToEgg");
			CharacterSetReactionPriority(_chicken,"DefaultWanderInTrigger",0);

			PROC
			Proc_RC_DW_VC_SetNewBroodChicken()
			THEN
			NOT DB_RC_DW_VC_DoneOnce(1);

			When the '''Proc_RC_DW_VC_SetNewBroodChicken''' gets called, it iterates over the chickens in the DB_RC_DW_VC_Chickens() database. Next, for each such chicken it checks whether it is alive (not dead), and if so, it selects that chicken as the one that should hatch the egg. Of course, we only want one chicken to do so. Therefore, as soon as we found an available chicken, we define the '''DB_RC_DW_VC_DoneOnce(1)''' fact and we also check on this condition to ensure that we do not select additional chickens afterwards.

			Note that the check for '''NOT DB_RC_DW_VC_DoneOnce(1)''' is the very last condition. This is important, because as explained in the section on the [[Osiris_Overview#Rule_Evaluation_State\|Osiris rule evaluation state]], semantically Osiris iterates over databases by making a local table that contains all matching facts and then iterating over those without revisiting conditions higher up. This means that the iteration would not abort if we wrote the check like this:

			PROC
			Proc_RC_DW_VC_SetNewBroodChicken()
			AND
			NOT DB_RC_DW_VC_DoneOnce(1)
			AND
			DB_RC_DW_VC_Chickens(_chicken,_dialog,_ad,0,_trigger)
			AND
			CharacterIsDead((CHARACTERGUID)_chicken,0)
			THEN
			DB_RC_DW_VC_DoneOnce(1);

			The reason is that Osiris would find that '''DB_RC_DW_VC_DoneOnce(1)''' is not defined at the time '''Proc_RC_DW_VC_SetNewBroodChicken()''' gets called. Next, it will start iterating over the '''DB_RC_DW_VC_Chickens()''' database without checking the '''DB_RC_DW_VC_DoneOnce()''' database ever again.

			=== Factoring Out Checks to Queries ===
			Queries offer an easy way to factor out searching logic and the associated book keeping from a proc. For example, we could rewrite the above using a query as follows:

			QRY
			QRY_RC_DW_VC_FindBoodChicken()
			AND
			DB_RC_DW_VC_Chickens(_chicken,_dialog,_ad,0,_trigger)
			AND
			CharacterIsDead((CHARACTERGUID)_chicken,0)
			AND
			NOT DB_RC_DW_VC_FindBoodChicken(_)
			THEN
			DB_RC_DW_VC_FindBoodChicken(_chicken);

			PROC
			Proc_RC_DW_VC_SetNewBroodChicken()
			AND
			QRY_RC_DW_VC_FindBoodChicken()
			AND
			DB_RC_DW_VC_FindBoodChicken(_chicken)
			AND
			DB_RC_DW_VC_Chickens(_chicken,_dialog,_ad,0,_trigger)
			THEN
			NOT DB_RC_DW_VC_FindBoodChicken(_chicken);
			NOT DB_RC_DW_VC_Chickens(_chicken,_dialog,_ad,0,_trigger);
			...

			In this case, there is no real gain to do this. However, if you need to look up several independent things in a loop, this pattern can make your code much clearer as all the "only once" checks are isolated in their individual queries. Be careful to never use this pattern (using a result DB from a query in the same rule that called the query) in rules whose trigger condition(s) consist exclusively of DB-checks, because otherwise you will trigger an [[Osiris_Gotchas#Osiris_bug_with_User_Queries_in_Rule_Conditions\|Osiris bug]].

			== QueryOnlyOnce ==
			[[Osiris/Shared/QueryOnlyOnce\|QueryOnlyOnce]] is a useful helper query that uses the principle above as a handy shortcut to execute something only once. Its documentation page contains a usage example. The query itself is also very simple:

			QRY
			QueryOnlyOnce((STRING)_OnlyOnceUUID)
			AND
			NOT DB_OnlyOnce(_OnlyOnceUUID)
			THEN
			DB_OnlyOnce(_OnlyOnceUUID);

			The query will only succeed if that DB is not yet defined. When it succeeds, it defines the DB so that future invocations of this query will fail.

	[[Category:Osiris]]		[[Category:Osiris]]