3. Scripting

Basics

The main way to code your mods in Nightmare Vision is via Haxe scripts. Supported file endings are .hx, .hxs, and .hscript.
There are a variety of script types in NightmareVision, ranging from note types to states.

Scripts are most often located in the scripts folder, but can also be in characters, events, stages, and more.
Specific information on script types can be found on their respective pages.

Returning in Scripts

Often times in scripts, there are specific functions you can override.
To do so, you simply have to return the value ScriptConstants.STOP_FUNC.

Any and all functions that are able to be overwritten with return ScriptConstants.STOP_FUNC; will be listed.

---

Global Functions

These functions are typically run across all types of scripts. Below will be a list of basic functions run by most, if not all script types.

---

Name	When the function is ran	Fields?
onLoad	Function is run immediately upon the script being loaded.
onCreatePost	Function is run after super.create();is called in the script's respective state.
onUpdate(elapsed:Float)	Function is run every time the function update is called.	elapsed:Float is the amount of time (in seconds) that has passed since the last update call.
onUpdatePost(elapsed:Float)	Function is run every time the function update is called, specifically after super.update(elapsed); is called.	elapsed:Float is the amount of time (in seconds) that has passed since the last update call.
onDestroy()	Function is run upon destruction of a state.
onSubstateOpen()	Function is run whenever the function openSubState is run.
onSubstateClose()	Function is run whenever the function close() is run in a SubState.
onStepHit()	Function is run every time a step passes. Only runs if proper song setup is done with funkin.backend.Conductor.
onBeatHit()	Function is run every time a beat passes. Only run if proper song setup is done with funkin.backend.Conductor.
onSectionHit()	Function is run every time a section passes. Only run if proper song setup is done with funkin.backend.Conductor

PlayState Functions

There are a variety of functions that are run in PlayState, correlating to specific PlayState functionality.
Below are sectioned tables with each script function run throughout PlayState.

---

Create functions

Name	When the function is run	Fields	Return Value
onAddSpriteGroups()	Function is run right before the stage is added, and the character groups are added to the stage. Best used for layering issues.		If ScriptConstants.STOP_FUNC is returned, none of the afformentioned variables will be added to the state.
preReceptorGeneration(strum, lane)	Run every time a PlayField (also known as a Strumline) is created.	The field strum is the PlayField object created when this function is run. The field lane is the Integer ID value of the lane. 0 is the player line, 1 is the opponent line, and so on.
postReceptorGeneration(strum, lane)	Run after each time a PlayField (also known as a Strumline) is created.	The field strum is the PlayField object created when this function is run. The field lane is the Integer ID value of the lane. 0 is the player line, 1 is the opponent line, and so on.
preNoteGeneration()	Function is run right before the song's chart is loaded & all of the Note objects are created.
preModifierGeneration()	Function is run before the Modchart system's modifiers are registered.
postModifierGeneration()	Function is run after the Modchart system's modifiers are registered.

---

Song-related Functions

Name	When the function is run	Fields	Return Value
onStartCountdown()	Function is run whenever the pre-song Countdown begins. If the countdown is skipped, it will run immediately as the song starts.		If ScriptConstants.STOP_FUNC is returned, the function will not run and the song will not start.
onCountdownTick(tick)	Function is run on each count of the countdown. Run four times sequentially on-beat with the song.	The field tick correlates to the current countdown's tick, starting at 0 and ending at 3.
onSongStart()	Function is run when the song begins.
onEndSong()	Function is run when the song completes.		If ScriptConstants.STOP_FUNC is returned, PlayState's end-song functions will not run.
onPause()	Function is run when the player pauses the song.		If ScriptConstants.STOP_FUNC is returned, the pause menu will not open.
onResume()	Function is run when the player resumes the song after pausing.
onGameOver()	Function is run when the player runs out of health and dies.		If ScriptConstants.STOP_FUNC is returned, PlayStates game-over functions will not run.
onMoveCamera(focus)	Function is run whenever the in-game camera moves to focus on another character.	The field focus is a string value that correlates to the currently-focused character. "boyfriend" is boyfriend, "dad" is dad, and "gf" is gf.

---

Input functions

The functions listed are what functions are run on every PlayState script, not note type scripts. Please refer to the note type script section of the wiki for more information on event scripts.

Name	When the function is run	Fields	Return Value
onGhostTap(key)	Function is run when the player presses a StrumNote without any notes being hit.	The field key is the FlxKey value corresponding to the key just pressed.
noteMissPress(key)	Function is run when the player presses a StrumNote without any notes being hit, with the ghost tapping setting disabled.	The field key is the FlxKey value corresponding to the key just pressed.
onKeyPress(key)	Function is run when the player presses a key.	The field key is the FlxKey value corresponding to the key just pressed.
onKeyRelease(key)	Function is run when the player releases a previously pressed key.	The field key is the FlxKey value corresponding to the key just pressed.

---

Event functions

The functions listed are what functions are run on every PlayState script, not event scripts. Please refer to the event script section of the wiki for more information on event scripts.

Name	When the function is run	Fields	Return Value
eventEarlyTrigger(name, value1, value2)	Function is run for every charted event. Meant for getting early / delayed timing of specific events.	The field name is the targeted event's name. The field value1 is the targeted event's first value. The field value2 is the targeted event's second value.	Return the integer value of how many milliseconds early your event should be triggered.
onEventPush(event)	Function is run when the event-note is registered when the chart is read. Typically used for creating / loading assets.	The field event is the EventNote object that is created upon read. Values are readable by calling event.name, event.value1, event.value2.
onFirstPush(event)	Function is run upon the first read of a specific event. For example, if Change Character is run 3 times in your song, it will only run for the first time the event is pushed.	The field event is the EventNote object that is created upon read. Values are readable by calling event.name, event.value1, event.value2.
onEvent(name, value1, value2)	Function is run every time a charted event occurs.	The field name is the targeted event's name. The field value1 is the targeted event's first value. The field value2 is the targeted event's second value.

---

Note functions

Name	When the function is run	Fields	Return Value
onSpawnNote(note)	Function is run before a Note object is created via the song chart being read.	The field note is the note object to be created.	If ScriptConstants.STOP_FUNC is returned, the note will not be spawned.
onSpawnNotePost(note)	Function is run after a Note object is created via the song chart being read.	The field note is the note object to be created.
noteMiss(note)	Function is run when the player misses a note.	The field note is the Note object that the player failed to press.
noteMissPress(key)	Function is run when the player presses a StrumNote without any notes being hit and their Ghost Tapping setting is disabled.	The field key is the FlxKey value corresponding to the key just pressed.
goodNoteHitPre(note)	Function is run when the player presses a note, but before any PlayState functionality runs.	The field note is the Note object that the player pressed.
opponentNoteHitPre(note)	Function is run when the opponent hits a note, but before any PlayState functionality runs.	The field note is the Note object that the opponent hit.
extraNoteHitPre(note)	Function is run when any strumline with an ID above 1 hits a note, but before any PlayState functionality runs.	The field note is the Note object that the strum pressed.
onGhostAnim(anim, note)	Function is run if the character who hit a note play's a double-note ghost effect.	The field anim is the string value of the animation the ghost is playing. The field note is the Note object corresponding to the note the character just hit.	If ScriptConstants.STOP_FUNC is returned, the character will not play a ghost note.
goodNoteHit(note)	Function is run when the player hits a note, after all PlayState functionality has run.	The field note is the Note object the player just hit.
opponentNoteHit(note)	Function is run when the opponent hits a note, after all PlayState functionality has run.	The field note is the Note object the opponent just hit.
extraNoteHit(note)	Function is run when the strumline with an ID above 0 or 1 hits a note, after all PlayState functionality has run.	The field note is the Note object the strumline just hit.
onSpawnNoteSplash(splash, note)	Function is run when a NoteSplash object is spawned on the player's receptors.	The field splash is the NoteSplash object that has been spawned. The field note is the Note object that caused the NoteSplash to spawn.

---

HUD functions

Name	When the function is run	Fields	Return Value
onPopUpScore(note, rating, ratingGraphic, ratingNumGroup)	Function is run when the player hits a note and the ratings/combo graphics appear on screen..	The field note is the Note object that the player pressed. The field rating is the Rating data class that the pop up reads from. The field ratingGraphic is the FlxSprite graphic of the rating graphic displayed on screen, such as "Sick!" or "shit". The field ratingNumGroup is the FlxTypedGroup of FlxSprite graphics that display the player's current combo.
onPopUpScorePost(note, rating, ratingGraphic, ratingNumGroup)	Function is run after the player hits a note and the ratings/combo graphics appear on screen..	The field note is the Note object that the player pressed. The field rating is the Rating data class that the pop up reads from. The field ratingGraphic is the FlxSprite graphic of the rating graphic displayed on screen, such as "Sick!" or "shit". The field ratingNumGroup is the FlxTypedGroup of FlxSprite graphics that display the player's current combo.
onUpdateScore(miss)	Function is run whenever the score values are updated on the HUD object scoreTxt.	The field miss is a Boolean value that says if the recently-hit note was hit with a high enough accuracy or not.	If ScriptConstants.STOP_FUNC is returned, the HUD object scoreTxt will not have its text values updated.
onRecalculateRating()	Function is run when the player's current rank / accuracy is being calculated.