Mod:Nebula's Mission Board/ Job callbacks - Revision history

MistressNebula: Account for 1.0.1 changes

2025-08-01T17:44:16Z

Account for 1.0.1 changes

← Older revision		Revision as of 17:44, 1 August 2025
Line 2:		Line 2:

	== Events ==		== Events ==
	There are a few places in which the library checks a job's <code>Callback</code> field. These are called "events", and there are ~~nine~~ in total. Most events can also be interrupted; we will discuss how to do that next.		There are a few places in which the library checks a job's <code>Callback</code> field. These are called "events", and there are ten in total. Most events can also be interrupted; we will discuss how to do that next.
	* <code>"JobTake"</code>: Happens when a job is taken using the board menu, or when <code>MissionGen:TakeJob(<board_id>, <index>)</code> is called directly. Interrupting this event will cause it to not add the job to the taken list or mark it as taken.		* <code>"JobTake"</code>: Happens when a job is taken using the board menu, or when <code>MissionGen:TakeJob(<board_id>, <index>)</code> is called directly. Interrupting this event will cause it to not add the job to the taken list or mark it as taken.
	* <code>"JobActivate"</code>: Called when a job is activated from the taken menu, or when <code>MissionGen:ToggleTakenJob(<index>)</code> is called directly on a currently inactive job. Interrupting this event will cause the job to not be activated.		* <code>"JobActivate"</code>: Called when a job is activated from the taken menu, or when <code>MissionGen:ToggleTakenJob(<index>)</code> is called directly on a currently inactive job. Interrupting this event will cause the job to not be activated.
	* <code>"JobDeactivate"</code> Called when a job is deactivated from the taken menu, or when <code>MissionGen:ToggleTakenJob(<index>)</code> is called directly on a currently active job. Interrupting this event will cause the job to not be deactivated.		* <code>"JobDeactivate"</code>: Called when a job is deactivated from the taken menu, or when <code>MissionGen:ToggleTakenJob(<index>)</code> is called directly on a currently active job. Interrupting this event will cause the job to not be deactivated.
	* <code>"DungeonStart"</code> Called right before checking if the job is supposed to have a guest. This event cannot be interrupted.		* <code>"DungeonStart"</code>: Called right before checking if the job is supposed to have a guest. This event cannot be interrupted.
	* <code>"FloorStart"</code> Called at the start of the destination floor of a job. Interrupting this event will prevent any battle event and floor generation step normally required by the job's type from ~~occurring at all~~.		* <code>"DungeonEnd"</code>: Called right before checking for job completion. This event cannot be interrupted.
	* <code>"JobComplete"</code> Called when a job is marked as completed, or when <code>MissionGen:MarkJobCompleted(<job>)</code> is called directly. Interrupting this event will prevent the job from being marked as completed.		* <code>"FloorStart"</code>: Called at the start of the destination floor of a job, right after applying the segment's generation steps but before applying the floor's specific generation steps. Interrupting this event will prevent any battle event and floor generation step normally required by the job's type from being added to the queue.
	* <code>"JobFail"</code> Called when a job is marked as failed, or when <code>MissionGen:MarkJobFailed(<job>)</code> is called directly. Interrupting this event will prevent the job from being marked as failed.		* <code>"JobComplete"</code>: Called when a job is marked as completed, or when <code>MissionGen:MarkJobCompleted(<job>)</code> is called directly. Interrupting this event will prevent the job from being marked as completed.
	* <code>"BeforeReward"</code> Called right before the reward cutscene is about to start for a specific job. Interrupting this event will skip the cutscene altogether.		* <code>"JobFail"</code>: Called when a job is marked as failed, or when <code>MissionGen:MarkJobFailed(<job>)</code> is called directly. Interrupting this event will prevent the job from being marked as failed.
	* <code>"AfterReward"</code> Called right after the reward cutscene ends for a specific job. Interrupting this event will prevent the job from being removed from the taken list.		* <code>"BeforeReward"</code>: Called right before the reward cutscene is about to start for a specific job. Interrupting this event will skip the cutscene altogether.
			* <code>"AfterReward"</code>: Called right after the reward cutscene ends for a specific job. Interrupting this event will prevent the job from being removed from the taken list.

	By attaching code to these events, one can change how the library handles a job; jobs that unlock their target dungeons when activated become possible, for example. Expert modders might even be able to create completely new types of jobs, given enough effort.		By attaching code to these events, one can change how the library handles a job; jobs that unlock their target dungeons when activated become possible, for example. Expert modders might even be able to create completely new types of jobs, given enough effort.
Line 19:		Line 20:
	* <code>cancel</code> - <code>boolean</code>: Begins equal to false. If true, it will interrupt the event if possible.		* <code>cancel</code> - <code>boolean</code>: Begins equal to false. If true, it will interrupt the event if possible.
	* <code>job</code> - <code>[[Mod:Nebula's Mission Board/ Job Table\|JobTable]]</code>: The job that this instance of the event applies to.		* <code>job</code> - <code>[[Mod:Nebula's Mission Board/ Job Table\|JobTable]]</code>: The job that this instance of the event applies to.
			* <code>data</code> - <code>table</code>: Some extra parameters that may be useful to the callback.

	This gives you full access to all data stored inside the job table, making it easy to write general purpose functions. Plus, as you can see, interrupting an event is as easy as setting <code>cancel</code> to <code>true</code>. The table will ~~then~~ be returned to the event-calling code, which will check for the field's state and react accordingly.		This gives you full access to all data stored inside the job table, making it easy to write general purpose functions. Plus, as you can see, interrupting an event is as easy as setting <code>cancel</code> to <code>true</code>. This is not all, though; the <code>data</code> table might contain different properties depending on the event. If an event is not on this list, its data table will be empty:
			* <code>"JobTake"</code>:
			** <code>board</code> - <code>string</code>: the id of the board this job is being taken from.
			* <code>"JobActivate"</code>: Nothing.
			* <code>"JobDeactivate"</code>: Nothing.
			* <code>"DungeonStart"</code>: Nothing.
			* <code>"DungeonEnd"</code>:
			** <code>result</code> - <code>[https://github.com/RogueCollab/RogueEssence/blob/master/RogueEssence/Data/GameProgress.cs#L72 ResultType]</code>: The final result of this exploration.
			* <code>"FloorStart"</code>:
			** <code>zoneContext</code> - <code>[https://github.com/RogueCollab/RogueEssence/blob/master/RogueEssence/LevelGen/Zones/ZoneSegment.cs#L288 ZoneGenContext]</code> the collection of zone gen data associated to the current task
			** <code>context</code> - any <code>[https://github.com/RogueCollab/RogueEssence/blob/master/RogueEssence/LevelGen/MapGenContext.cs BaseMapGenContext]</code> implementation: an object that describes the map in its during-generation state
			** <code>queue</code> - <code>[https://github.com/audinowho/RogueElements/blob/master/RogueElements/StablePriorityQueue.cs StablePriorityQueue]<[https://github.com/audinowho/RogueElements/blob/master/RogueElements/Priority/Priority.cs Priority],any [https://github.com/audinowho/RogueElements/blob/master/RogueElements/MapGen/IGenStep.cs IGenStep] implementation></code>: the list of floor generation steps to apply after this callback returns.
			** <code>seed</code> - <code>integer</code>: the numeric seed supplied to the ZoneStep that is handling this code.
			* <code>"BeforeReward"</code>:
			** <code>zone</code> - <code>string</code> the id of the zone the player is currently in.
			** <code>map</code> - <code>integer</code> the index of the map the player is currently in.
			* <code>"AfterReward"</code>:
			** <code>zone</code> - <code>string</code> the id of the zone the player is currently in.
			** <code>map</code> - <code>integer</code> the index of the map the player is currently in.
			After the callback returns, the table will be returned to the event-calling code, which will check for the field's state and react accordingly.

	== Callbacks ==		== Callbacks ==

MistressNebula: Make page

2025-07-30T15:43:09Z

Make page

New page

The library contains a callback system that allows modders to attach code to specific jobs to customize their behavior. It functions very similarly to how the base game handles scripted events: you attach a function name and a series of arguments to an id, and the system will fetch a function from somewhere, passing those arguments to it. Let's see exactly how this works.

== Events ==
There are a few places in which the library checks a job's <code>Callback</code> field. These are called "events", and there are nine in total. Most events can also be interrupted; we will discuss how to do that next.
* <code>"JobTake"</code>: Happens when a job is taken using the board menu, or when <code>MissionGen:TakeJob(<board_id>, <index>)</code> is called directly. Interrupting this event will cause it to not add the job to the taken list or mark it as taken.
* <code>"JobActivate"</code>: Called when a job is activated from the taken menu, or when <code>MissionGen:ToggleTakenJob(<index>)</code> is called directly on a currently inactive job. Interrupting this event will cause the job to not be activated.
* <code>"JobDeactivate"</code> Called when a job is deactivated from the taken menu, or when <code>MissionGen:ToggleTakenJob(<index>)</code> is called directly on a currently active job. Interrupting this event will cause the job to not be deactivated.
* <code>"DungeonStart"</code> Called right before checking if the job is supposed to have a guest. This event cannot be interrupted.
* <code>"FloorStart"</code> Called at the start of the destination floor of a job. Interrupting this event will prevent any battle event and floor generation step normally required by the job's type from occurring at all.
* <code>"JobComplete"</code> Called when a job is marked as completed, or when <code>MissionGen:MarkJobCompleted(<job>)</code> is called directly. Interrupting this event will prevent the job from being marked as completed.
* <code>"JobFail"</code> Called when a job is marked as failed, or when <code>MissionGen:MarkJobFailed(<job>)</code> is called directly. Interrupting this event will prevent the job from being marked as failed.
* <code>"BeforeReward"</code> Called right before the reward cutscene is about to start for a specific job. Interrupting this event will skip the cutscene altogether.
* <code>"AfterReward"</code> Called right after the reward cutscene ends for a specific job. Interrupting this event will prevent the job from being removed from the taken list.

By attaching code to these events, one can change how the library handles a job; jobs that unlock their target dungeons when activated become possible, for example. Expert modders might even be able to create completely new types of jobs, given enough effort.

=== The Event Table ===
When an event is called, a small table of data is generated and then passed to whatever callback is assigned to it. This table contains the following data:
* <code>cancel</code> - <code>boolean</code>: Begins equal to false. If true, it will interrupt the event if possible.
* <code>job</code> - <code>[[Mod:Nebula's Mission Board/ Job Table|JobTable]]</code>: The job that this instance of the event applies to.

This gives you full access to all data stored inside the job table, making it easy to write general purpose functions. Plus, as you can see, interrupting an event is as easy as setting <code>cancel</code> to <code>true</code>. The table will then be returned to the event-calling code, which will check for the field's state and react accordingly.

== Callbacks ==
To use the callback system, you first need to set the [[Mod:Nebula's Mission Board/ Editing settings#mission_callback_root|mission_callback_root]] setting to a global table of your choice. All callbacks will then need to be stored inside that table. Furthermore, this is what their signature should look like:
<pre>
function(<evt>, <args>)
</pre>
where:
* <code>evt</code> is the event table discussed above
* <code>args</code> is the list of arguments set when registering the callback.

Any changes to the job table will be kept after the callback ends, so you can even use this to change the job's properties if you want.

=== Registering a callback ===
Once you have your callback ready, you need to register it to a job. This is done by using this function:
<pre>
MissionGen:RegisterCallback(<job>, <event>, <func>, <args>)
</pre>
where:
* <code>job</code> is the job table to add the callback to.
* <code>event</code> is the id of the event to subscribe to, as discussed at the top.
* <code>func</code> is the name of the callback function.
* <code>event</code> is optional, and is the table of arguments to pass to this instance of the callback. If not set, it defaults to an empty table. You should not save C# objects or functions in here, because they wouldn't be saved correctly.

This will make it so that the given function is called when the given event is triggered. Do keep in mind that only one callback per event can be registered inside a job. Trying to register a second function will remove the previous one.

Once your callback is registered, just give the job to the player in some way, and you're good to go.