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 noteskins, 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 Function_Stop.

Any and all functions that are able to be overwritten with return Function_Stop; 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.
onOpenSubState()	Function is run whenever the function openSubState is run.
onCloseSubState()	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 Function_Stop 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.
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 Function_Stop 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.
onSongEnd()	Function is run when the song completes.		If Function_Stop is returned, PlayState's end-song functions will not run.
onPause()	Function is run when the player pauses the song.		If Function_Stop 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 Function_Stop 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.
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 Function_Stop is returned, the HUD object scoreTxt will not have its text values updated.
onPopUpScore(note, rating)	Function is run when the HUD rating & combo number graphics appear on screen.	The field note is the Note object that was hit to cause the score to appear. The field rating is the Rating value corresponding to the recently-hit note.
onPopUpScorePost(note, rating)	Function is run after the HUD rating & combo number graphics appear on screen.	The field note is the Note object that was hit to cause the score to appear. The field rating is the Rating value corresponding to the recently-hit note.

---

Key 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.
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
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 Function_Stop 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.