Skip to content

Commit f43194a

Browse files
KoloInDaCribKade-github
KoloInDaCrib
authored and
Kade-github
committed
Script Event Callbacks article
Co-Authored-By: Kolo <[email protected]>
1 parent 58da0f2 commit f43194a

File tree

1 file changed

+240
-0
lines changed

1 file changed

+240
-0
lines changed

‎assets/content/cookbook/Advanced/8.ScriptEventCallbacks.md

Lines changed: 240 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,240 @@
1+
[tags]: / "advanced,hscript"
2+
3+
# Script Event Callbacks
4+
5+
This chapter will walk you through the process of using script event callbacks for a more advanced custom behaviour, which will get called whenever a certain event within the game happens.
6+
7+
Several base classes use functions that get an event dispatched to them whenever something in the game happens, such as when getting created or destroyed. With your scripted class, you can override these callbacks to perform custom behavior when these would receive a dispatched event. Not every base class has every callback to their disposal.
8+
9+
## List of Script Event Callbacks
10+
11+
There is a predefined list of every script event callback the game has set up to be overridable, with their respective event type whose fields you can read from or write to. More of these will be added to the future.
12+
13+
- `onScriptEvent(event:ScriptEvent)` - Called when any sort of script event would get dispatched. This is called before the event's respective callback.
14+
- Available to Songs, Stage Props, Boppers, Characters, Stages, Backing Cards, Note Kinds, Dialogue Boxes, Speakers, Conversations and Modules.
15+
- `onCreate(event:ScriptEvent)` - Called when the base class gets created in the game.
16+
- Available to Songs, Stage Props, Boppers, Characters, Stages, Backing Cards, Note Kinds, Dialogue Boxes, Speakers, Conversations and Modules.
17+
- `onDestroy(event:ScriptEvent)` - Called when the base class gets destroyed in the game.
18+
- Available to Songs, Stage Props, Boppers, Characters, Stages, Backing Cards, Note Kinds, Dialogue Boxes, Speakers, Conversations and Modules.
19+
- `onUpdate(event:UpdateScriptEvent)` - Called when the base class gets updated in the game.
20+
- Available to Songs, Stage Props, Boppers, Characters, Stages, Backing Cards, Note Kinds, Dialogue Boxes, Speakers, Conversations and Modules.
21+
- `onStateChangeBegin(event:StateChangeScriptEvent)` - Called when the State changing process begins.
22+
- Available to Backing Cards and Modules.
23+
- `onStateChangeEnd(event:StateChangeScriptEvent)` - Called when the State changing process ends.
24+
- Available to Backing Cards and Modules.
25+
- `onSubStateOpenBegin(event:SubStateScriptEvent)` - Called when the SubState opening process begins.
26+
- Available to Backing Cards and Modules.
27+
- `onSubStateOpenEnd(event:SubStateScriptEvent)` - Called when the SubState opening process ends.
28+
- Available to Backing Cards and Modules.
29+
- `onSubStateCloseBegin(event:SubStateScriptEvent)` - Called when the SubState closing process begins.
30+
- Available to Backing Cards and Modules.
31+
- `onSubStateCloseEnd(event:SubStateScriptEvent)` - Called when the SubState closing process ends.
32+
- Available to Backing Cards and Modules.
33+
- `onFocusLost(event:FocusScriptEvent)` - Called when the focus from the game window is lost.
34+
- Available to Backing Cards and Modules.
35+
- `onFocusGained(event:FocusScriptEvent)` - Called when the focus from the game window is gained.
36+
- Available to Backing Cards and Modules.
37+
- `onAdd(event:ScriptEvent)` - Called when the base class is added to the game stage.
38+
- Available to Stage Props, Boppers and Characters.
39+
- `onNoteIncoming(event:NoteScriptEvent)` - Called when a note is within the field of view.
40+
- Available to Songs, Boppers, Characters, Stages, Notekinds and Modules.
41+
- `onNoteHit(event:HitNoteScriptEvent)` - Called when a note is hit by either character.
42+
- Available to Songs, Boppers, Characters, Stages, Notekinds and Modules.
43+
- `onNoteMiss(event:NoteScriptEvent)` - Called when a note is missed by either character.
44+
- Available to Songs, Boppers, Characters, Stages, Notekinds and Modules.
45+
- `onNoteHoldDrop(event:HoldNoteScriptEvent)` - Called when a hold note is dropped by either character.
46+
- Available to Songs, Boppers, Characters, Stages, Notekinds and Modules.
47+
- `onStepHit(event:SongTimeScriptEvent)` - Called when the Conductor reaches a new step of the music.
48+
- Available to Songs, Boppers, Characters, Stages, Backing Cards and Modules.
49+
- `onBeatHit(event:SongTimeScriptEvent)` - Called when the Conductor reaches a new beat of the music.
50+
- Available to Songs, Boppers, Characters, Stages, Backing Cards and Modules.
51+
- `onPause(event:PauseScriptEvent)` - Called when the main gameplay is paused.
52+
- Available to Songs, Boppers, Characters, Stages and Modules.
53+
- `onResume(event:ScriptEvent)` - Called when the main gameplay is resumed.
54+
- Available to Songs, Boppers, Characters, Stages and Modules.
55+
- `onSongLoaded(event:SongLoadScriptEvent)` - Called when song chart has been parsed but before the notes have been placed, both when starting the song for the first time and retrying the song.
56+
- Available to Songs, Boppers, Characters, Stages and Modules.
57+
- `onSongStart(event:ScriptEvent)` - Called when the song starts.
58+
- Available to Songs, Boppers, Characters, Stages and Modules.
59+
- `onSongEnd(event:ScriptEvent)` - Called when the song ends.
60+
- Available to Songs, Boppers, Characters, Stages and Modules.
61+
- `onGameOver(event:ScriptEvent)` - Called when the player runs out of health but before the game over substate is opened.
62+
- Available to Songs, Boppers, Characters, Stages and Modules.
63+
- `onSongRetry(event:SongRetryEvent)` - Called when the song retrying process begins, either through the pause menu or through the game over screen.
64+
- Available to Songs, Boppers, Characters, Stages and Modules.
65+
- `onNoteGhostMiss(event:GhostMissNoteScriptEvent)` - Called when the player pressed a key with no notes on the strumline.
66+
- Available to Songs, Boppers, Characters, Stages and Modules.
67+
- `onSongEvent(event:SongEventScriptEvent)` - Called when a song event (such as Focus Camera) is triggered.
68+
- Available to Songs, Boppers, Characters, Stages and Modules.
69+
- `onCountdownStart(event:CountdownScriptEvent)` - Called when the countdown is about to start.
70+
- Available to Songs, Boppers, Characters, Stages and Modules.
71+
- `onCountdownStep(event:CountdownScriptEvent)` - Called when a countdown changes its current step.
72+
- Available to Songs, Boppers, Characters, Stages and Modules.
73+
- `onCountdownEnd(event:CountdownScriptEvent)` - Called when the countdown ends.
74+
- Available to Songs, Boppers, Characters, Stages and Modules.
75+
- `onDialogueCompleteLine(event:DialogueScriptEvent)` - Called when the player advanced the dialogue while it's being typed.
76+
- Available to Dialogue Boxes, Speakers and Conversations.
77+
- `onDialogueLine(event:DialogueScriptEvent)` - Called when the player advances the dialogue while it's idling.
78+
- Available to Dialogue Boxes, Speakers and Conversations.
79+
- `onDialogueSkip(event:DialogueScriptEvent)` - Called when the dialogue gets skipped.
80+
- Available to Dialogue Boxes, Speakers and Conversations.
81+
- `onDialogueEnd(event:DialogueScriptEvent)` - Called when the dialogue ends.
82+
- Available to Dialogue Boxes, Speakers and Conversations.
83+
84+
## List of Event Types
85+
86+
There is a predefined list of script events, whose fields are readable and, in some cases, changeable, that get dispatched to script event callbacks. More of these will be added in the future. See above which callback accepts which event.
87+
88+
- `ScriptEvent`, with fields:
89+
- (read-only) `cancelable` - If the event can be canceled.
90+
- (read-only) `type` - The type of the event.
91+
- (read-only) `shouldPropagate` - If the event can be dispatched to its respective callback. If false, it will only get dispatched to `onScriptEvent`.
92+
- (read-only) `eventCanceled` - If the event has been cancelled.
93+
- `cancelEvent()` - Cancels the event, if possible.
94+
- `cancel()` - Cancels the event, if possible.
95+
- `stopPropagation()` - Stops the propagation of this event.
96+
97+
- `UpdateScriptEvent`, with fields:
98+
- Inherited from `ScriptEvent`.
99+
- (read-only) `elapsed` - How much time has passed since the last update.
100+
101+
- `StateChangeScriptEvent`, with fields:
102+
- Inherited from `ScriptEvent`.
103+
- (read-only) `targetState` - The State that was switched to.
104+
105+
- `SubStateScriptEvent`, with fields:
106+
- Inherited from `ScriptEvent`.
107+
- (read-only) `targetState` - The SubState that was opened/closed.
108+
109+
- `FocusScriptEvent`, with fields:
110+
- Inherited from `ScriptEvent`.
111+
112+
- `NoteScriptEvent`, with fields:
113+
- Inherited from `ScriptEvent.`
114+
- (read-only) `note` - The NoteSprite associated with this event.
115+
- (read-only) `comboCount` - The currently ongoing combo.
116+
- `playSound` - Whether to play a miss sound when missing a note.
117+
- `healthChange` - The amount of health to add to the player. Can be a negative value too.
118+
119+
- `HitNoteScriptEvent`, with fields:
120+
- Inherited from `NoteScriptEvent`.
121+
- `judgement` - The judgement received from hitting the note.
122+
- `score` - The score received from hitting the note.
123+
- `isComboBreak` - If the hit caused a combo break.
124+
- `hitDiff` - The time difference (in miliseconds) when the player hit the note.
125+
- `doesNotesplash` - If the note does a splash, defaults to true when the judgement is "sick".
126+
127+
- `HoldNoteScriptEvent`, with fields:
128+
- Inherited from `NoteScriptEvent`.
129+
- `holdNote` - The SustainTrail object associated with this event.
130+
- `score` - The score received from hitting the note.
131+
- `isComboBreak` - If the hit caused a combo break.
132+
- `hitDiff` - The time difference (in miliseconds) when the player hit the note.
133+
- `doesNotesplash` - If the note does a splash, defaults to true when the judgement is "sick".
134+
135+
- `SongTimeScriptEvent`, with fields:
136+
- Inherited from `ScriptEvent`.
137+
- (read-only) `beat` - The current beat of the song.
138+
- (read-only) `step` - The current step of the song.
139+
140+
- `PauseScriptEvent`, with fields:
141+
- Inherited from `ScriptEvent`.
142+
- `gitaroo` - If the Gitaroo Man easter egg should be used.
143+
144+
- `SongLoadScriptEvent`, with fields:
145+
- Inherited from `ScriptEvent`.
146+
- (read-only) `id` - The song id associated with the event.
147+
- (read-only) `difficulty` - The song difficulty associated with the event.
148+
- `notes` - An Array of SongNoteData objects representing the notes for the chart.
149+
- `events` - An Array of SongEventData objects representing the events for the chart.
150+
151+
- `SongRetryEvent`, with fields:
152+
- Inherited from `ScriptEvent`.
153+
- (read-only) `difficulty` - The new difficulty of the song.
154+
155+
- `GhostMissNoteScriptEvent`, with fields:
156+
- Inherited from `ScriptEvent`.
157+
- (read-only) `dir` - The direction (1-4) that was mistakenly pressed.
158+
- (read-only) `hasPossibleNotes` - If there were notes within judgement range when the key was pressed.
159+
- `healthChange` - The amount of health to add to the player. Can be a negative value too.
160+
- `scoreChange` - The amount of score to add to the player. Can be a negative value too.
161+
- `playSound` - Whether to play a miss sound.
162+
- `playAnim` - Whether to play a miss animation.
163+
164+
- `SongEventScriptEvent`, with fields:
165+
- Inherited from `ScriptEvent`.
166+
- (read-only) `eventData` - The SongEventData object associated with the event.
167+
168+
- `CountdownScriptEvent`, with fields:
169+
- Inherited from `ScriptEvent`.
170+
- (read-only) `step` - The current countdown step. Can be *BEFORE*, *THREE*, *TWO*, *ONE*, *GO* or *AFTER*.
171+
172+
- `DialogueScriptEvent`, with fields:
173+
- Inherited from `ScriptEvent`.
174+
- (read-only) `conversation` - The Conversation object associated with the event.
175+
176+
## Script Event Cancelling
177+
178+
While most cannot be cancelled, cancelling some events provides more leeway to the custom behavior. An example to this would be having pre-song cutscenes, as seen in the script file for the song Darnell[^darnell]:
179+
```haxe
180+
// ...
181+
182+
// Line 78
183+
public override function onCountdownStart(event:CountdownScriptEvent):Void
184+
{
185+
super.onCountdownStart(event);
186+
187+
// ...
188+
189+
if (hasPlayedCutscene && !hasPlayedInGameCutscene)
190+
{
191+
trace('Pausing countdown to play in game cutscene');
192+
193+
hasPlayedInGameCutscene = true;
194+
195+
event.cancel(); // CANCEL THE COUNTDOWN!
196+
197+
PlayState.instance.camHUD.visible = false;
198+
introCutscene();
199+
}
200+
201+
// ...
202+
203+
}
204+
205+
// ...
206+
```
207+
208+
## Overriding Script Event Callbacks
209+
210+
Even if most base classes have the script event callbacks as empty functions, others have behavior that is entirely dependant on them. As such, you can skip the behavior or call it under a condition depending on if and where you put your super function call. One such example is in the script file for Boyfriend (Christmas)[^bf-christmas]:
211+
```haxe
212+
// ...
213+
214+
function onNoteHit(event:HitNoteScriptEvent)
215+
{
216+
// ...
217+
218+
// Override the hit note animation.
219+
switch (event.note.kind)
220+
{
221+
case "censor":
222+
holdTimer = 0;
223+
this.playSingAnimation(event.note.noteData.getDirection(), false, 'censor');
224+
return;
225+
case "hey":
226+
holdTimer = 0;
227+
this.playAnimation('hey', true, true);
228+
return;
229+
default:
230+
super.onNoteHit(event);
231+
}
232+
}
233+
}
234+
235+
// ...
236+
```
237+
[^darnell]: <https://github.com/FunkinCrew/funkin.assets/blob/main/preload/scripts/songs/darnell.hxc>
238+
[^bf-christmas]: <https://github.com/FunkinCrew/funkin.assets/blob/main/preload/scripts/characters/bf-christmas.hxc>
239+
240+
> Author: [KoloInDaCrib](https://github.com/KoloInDaCrib)

0 commit comments

Comments
 (0)