### Custom State & Substate Setup

Source: https://context7.com/nmvteam/nightmarevision/llms.txt

Example of setting up a custom menu state, including music playback, Conductor BPM synchronization, and UI element updates on beat.

```haxe
// scripts/states/MyMenuState.hx

import funkin.audio.FunkinSound;
import funkin.backend.Conductor;

var menuTitle:FlxText;

function onLoad() {
    // Start playing music and sync the Conductor BPM
    FunkinSound.playMusic(Paths.music("menu-theme"));
    Conductor.bpm = 120;
}

function onCreate() {
    menuTitle = new FlxText(0, 100, FlxG.width, "My Custom Menu", 48);
    menuTitle.alignment = CENTER;
    add(menuTitle);
}

function onCreatePost() {
    // All FlxState internals are ready here
}

function onUpdate(elapsed:Float) {
    // Keep Conductor in sync with the playing music
    if (FlxG.sound.music != null)
        Conductor.songPosition = FlxG.sound.music.time;
}

function onBeatHit() {
    menuTitle.scale.set(1.05, 1.05); // pulse on every beat
}

// --- Switching to this state from anywhere ---
// FlxG.switchState(() -> { new ScriptedState("MyMenuState"); });

// --- Opening a substate ---
// openSubstate(new ScriptedSubstate("MyPauseSubstate"));
```

--------------------------------

### Install Project Libraries with hxpkg and hmm (Advanced)

Source: https://github.com/nmvteam/nightmarevision/blob/dev/README.md

This advanced method uses hxpkg to convert dependencies to the hmm format, then utilizes cargo and hmm-rs for faster installation. Rust must be installed.

```sh
haxelib git hxpkg https://github.com/ADA-Funni/hxpkg add-hmm-compatibility
haxelib run hxpkg to-hmm

car go install --git https://github.com/ninjamuffin99/hmm-rs hmm-rs
hmm-rs clean
hmm-rs install

haxelib fixrepo

haxelib install hmm
haxelib remove grig.audio
haxelib run hmm reinstall grig.audio

haxelib fixrepo
```

--------------------------------

### Example freeplay.json Configuration

Source: https://github.com/nmvteam/nightmarevision/wiki/2.-Basic-Set‐up

This example demonstrates how to structure the freeplay.json file to include multiple tabs with different song sources. It shows how to group songs by referencing week JSONs and by directly listing song folder names.

```json
{
    "tabs": [
        {
            "title": "Friday Night Funkin'",
            "fromWeeks": ["tutorial", "week1", "week1-pico", "week2", "week3", "week4", "week5", "week6", "week7"]
        },
        {
            "title": "Erect Mixes",
            "songs": [
                "Bopeebo-erect",
                "Fresh-erect",
                "Dadbattle-erect"
            ]
        },
        {
            "title": "Pico Mixes",
            "songs": [
                "Bopeebo (Pico Mix)",
                "Fresh (Pico Mix)",
                "DadBattle (Pico Mix)",
                "Stress (Pico Mix)",
                "Darnell",
                "Lit-Up",
                "2hot",
                "Blazin"
            ]
        }   
    ]
}
```

--------------------------------

### Install Project Libraries with hxpkg

Source: https://github.com/nmvteam/nightmarevision/blob/dev/README.md

Use this command to install project dependencies via hxpkg. This method is recommended for its simplicity but may be slower.

```sh
haxelib git hxpkg https://github.com/ADA-Funni/hxpkg add-hmm-compatibility
haxelib run hxpkg install
```

--------------------------------

### Example meta.json configuration

Source: https://github.com/nmvteam/nightmarevision/wiki/2.-Basic-Set‐up

This JSON object demonstrates a typical configuration for a mod's `meta.json` file, including settings for name, description, global, discordClientID, windowTitle, iconFile, defaultTransition, stateRedirects, and various UI prefixes.

```json
{
    "name": "Friday Night Funkin: D-Sides (REDUX)",
    "description": "The iconic remix mod of the newgrounds-born rhythm game, Friday Night Funkin'! With a nearly identical premise as the original game, face off against a variety of opponents with a creative spin, alongside creative interpretation of many fanworks!",
    "global": false,

    "discordClientID": "960620410095956018",
    "windowTitle": "Friday Night Funkin: D-Sides",
    "iconFile": "UI/window/icons/64",
    "defaultTransition": "SimpleSticker",
    
    "stateRedirects": {
        "TitleState": "TitleState",
        "MainMenuState": "MainMenuState",
        "StoryMenuState": "StoryMenuState",
        "FreeplayState": "FreeplayState",
        "CreditsState": "Credits",
        "OptionsState": "Options"
    },
    

    "uiPrefix": "UI/game/HUD/",
    "countdownPrefix": "UI/game/HUD/countdown/",
    "ratingsPrefix": "UI/game/HUD/ratings/"
}
```

--------------------------------

### NightmareVision Compilation Steps

Source: https://context7.com/nmvteam/nightmarevision/llms.txt

Provides a sequence of commands for setting up the development environment and compiling NightmareVision. This includes installing the hxpkg library manager, installing dependencies via hxpkg or hmm-rs, and rebuilding Lime's native layer.

```sh
# 1. Install the hxpkg library manager
haxelib git hxpkg https://github.com/ADA-Funni/hxpkg add-hmm-compatibility

# 2a. Recommended: install all libraries via hxpkg
haxelib run hxpkg install

# 2b. Advanced (requires Rust): faster parallel install via hmm-rs
haxelib run hxpkg to-hmm
cargo install --git https://github.com/ninjamuffin99/hmm-rs hmm-rs
hmm-rs clean && hmm-rs install
haxelib fixrepo
haxelib install hmm
haxelib remove grig.audio
haxelib run hmm reinstall grig.audio
haxelib fixrepo

# 3. Rebuild Lime's native C++ layer
haxelib run lime rebuild cpp -release

# 4. Compile and run (Windows, release build)
haxelib run lime test windows -release
```

--------------------------------

### Queue Modifier Value Easing

Source: https://github.com/nmvteam/nightmarevision/wiki/5.-Modcharts-&-Modifiers-(WIP)

Queue a modifier value to ease from a start value to a target value over a specified duration. You can choose from various easing styles available in FlxEase. The player argument specifies which strumline receives the effect.

```javascript
modManager.queueEase(16, 32, "squish", 1, "bounceOut", 0);
```

--------------------------------

### Setting up Conductor for Beat Functions

Source: https://github.com/nmvteam/nightmarevision/wiki/4.-Custom-States-&-Substates

Configure Conductor to enable `onStepHit`, `onBeatHit`, and `onSectionHit` functions. Ensure the music is playing and set the correct BPM.

```haxe
import funkin.audio.FunkinSound;
import funkin.backend.Conductor;

function onLoad()
{
  FunkinSound.playMusic(Paths.music("Your song here"));
  Conductor.bpm = 150; // set this to your song's bpm
}

function onUpdate(elapsed:Float)
{
  if (FlxG.sound.music != null)
    Conductor.songPosition = FlxG.sound.music.time;
}
```

--------------------------------

### Opening a Custom State

Source: https://github.com/nmvteam/nightmarevision/wiki/4.-Custom-States-&-Substates

Switch to a custom state by providing its script location. The `scripts/states/` path and file extension are omitted.

```haxe
FlxG.switchState(()->{new ScriptedState("script location")});
```

```haxe
FlxG.switchState(()->{new ScriptedState("TestState")});
```

```haxe
FlxG.switchState(()->{new ScriptedState("organization/TestState")});
```

--------------------------------

### Opening a Custom Substate

Source: https://github.com/nmvteam/nightmarevision/wiki/4.-Custom-States-&-Substates

Open a custom substate by providing its script location. The `scripts/substates/` path and file extension are omitted.

```haxe
openSubstate(new ScriptedSubstate("script location");
```

```haxe
openSubstate(new ScriptedSubstate("TestSubstate");
```

```haxe
openSubstate(new ScriptedSubstate("organization/TestSubstate");
```

--------------------------------

### Rebuild and Test Lime Project

Source: https://github.com/nmvteam/nightmarevision/blob/dev/README.md

After setting up libraries, rebuild the cpp target for Lime in release mode, then run a test compilation for Windows. This ensures the project is compiling correctly.

```sh
haxelib run lime rebuild cpp -release
haxelib run lime test windows -release
```

--------------------------------

### Configure meta.json Combo Prefix

Source: https://github.com/nmvteam/nightmarevision/wiki/2.-Basic-Set‐up

Defines the prefix for UI game HUD combo assets within the meta.json configuration.

```json
{
    "comboPrefix": "UI/game/HUD/combo/"
}
```

--------------------------------

### ModManager: Real-time Visual Modifiers

Source: https://context7.com/nmvteam/nightmarevision/llms.txt

Demonstrates setting, queuing, and easing visual modifiers on playfields. Requires importing `flixel.math.FlxAngle` for radian conversions. Modifiers can be applied instantly, at specific song steps, or with easing.

```haxe
// scripts/modchart-demo.hx
// All three ModManager methods demonstrated together

function onSongStart() {
    // 1. Set immediately — drunk wobble on the player field (field 0)
    modManager.setValue("drunk", 1, 0);

    // 2. Queue a value change at step 32 on both fields (player = -1)
    modManager.queueSet(32, "alpha", 0.5, -1);

    // 3. Ease squish in from step 16 to 32 on field 0 with bounceOut
    modManager.queueEase(16, 32, "squish", 1, "bounceOut", 0);

    // Rotation modifiers take RADIANS — use FlxAngle.TO_RAD to convert
    // Rotate the player's down-arrow (ID 1) 90° around the screen center on X:
    import flixel.math.FlxAngle;
    modManager.queueEase(64, 80, "centerrotate1X", 90 * FlxAngle.TO_RAD, "linear", 0);
}

function onBeatHit() {
    // Beat-synced tipsy (vertical wave) on the opponent field
    modManager.setValue("tipsy", 0.8, 1);
}
```

--------------------------------

### NightmareVision Mod Folder Structure

Source: https://context7.com/nmvteam/nightmarevision/llms.txt

Outlines the recommended directory layout for NMV mods, separating assets and scripts for clarity. Songs include their own audio and chart sub-folders, while scripts are categorized under `scripts/`.

```plaintext
content/YourMod/
├── meta.json                  ← mod metadata
├── data/
│   ├── freeplay.json
│   ├── characters/            ← character .json files
│   ├── events/                ← event .hx / .txt files
│   ├── notetypes/             ← note type .hx / .txt files
│   ├── noteskins/             ← note skin .json files
│   ├── stages/your-stage/     ← data.json + script.hx
│   └── weeks/                 ← week .json files
├── images/
│   └── ui/icons/              ← health bar icons
├── scripts/
│   ├── states/                ← custom FlxState scripts
│   ├── substates/             ← custom FlxSubState scripts
│   ├── transitions/
│   └── plugins/
├── songs/your-song/
│   ├── meta.json              ← song metadata
│   ├── audio/
│   │   ├── Inst.ogg
│   │   ├── Voices-player.ogg
│   │   └── Voices-opp.ogg
│   └── charts/
│       ├── hard.json
│       └── events.json
├── fonts/
├── music/
├── sounds/
├── shaders/                   ← .frag GLSL shaders
└── videos/                    ← .mp4 / .mov cutscenes
```

--------------------------------

### PlayState Note Callbacks

Source: https://context7.com/nmvteam/nightmarevision/llms.txt

Callbacks for fine-grained control over note spawning, hitting, and missing. Useful for modifying note properties or customizing hit feedback.

```haxe
function onSpawnNote(note) {
    // Runs before a Note object is finalized; modify note properties here
    if (note.noteData == 0) note.x += 50; // offset left-arrow notes
    // return ScriptConstants.STOP_FUNC; // skip spawning this note
}

function goodNoteHitPre(note) {
    // Runs before PlayState processes the hit — ideal for early overrides
}

function goodNoteHit(note) {
    // Runs after PlayState processes the hit
    trace("Player hit a " + note.noteData + " note!");
}

function opponentNoteHit(note) {
    trace("Opponent hit note: " + note.noteData);
}

function noteMiss(note) {
    trace("Missed note: " + note.noteData);
}

function onSpawnNoteSplash(splash, note) {
    // Fired when a NoteSplash appears on the player's receptor
    splash.alpha = 0.8;
}

function onPopUpScore(note, rating, ratingGraphic, ratingNumGroup) {
    // Customize rating pop-up visuals
    ratingGraphic.scale.set(1.2, 1.2);
}

function onUpdateScore(miss:Bool) {
    // return ScriptConstants.STOP_FUNC; // prevent scoreTxt from auto-updating
}
```

--------------------------------

### PlayState Song & Input Callbacks

Source: https://context7.com/nmvteam/nightmarevision/llms.txt

Callbacks for managing the song lifecycle and player input. Some callbacks can prevent default behavior by returning ScriptConstants.STOP_FUNC.

```haxe
function onStartCountdown() {
    trace("Countdown starting!");
    // return ScriptConstants.STOP_FUNC; // would prevent the song from starting
}

function onCountdownTick(tick:Int) {
    // tick = 0..3
    trace("Tick: " + tick);
}

function onSongStart() {
    trace("Song started!");
}

function onEndSong() {
    trace("Song finished!");
    // return ScriptConstants.STOP_FUNC; // suppress default end-song behaviour
}

function onPause() {
    trace("Game paused");
    // return ScriptConstants.STOP_FUNC; // prevent pause menu from opening
}

function onGameOver() {
    trace("Player died");
    // return ScriptConstants.STOP_FUNC; // suppress game-over screen
}

function onMoveCamera(focus:String) {
    // focus: "boyfriend" | "dad" | "gf"
    trace("Camera now on: " + focus);
}

function onKeyPress(key:Int) {
    trace("Key pressed: " + key);
}

function onKeyRelease(key:Int) {
    trace("Key released: " + key);
}

function onGhostTap(key:Int) {
    // Player pressed a receptor with no hittable note (ghost tapping enabled)
}
```

--------------------------------

### PlayState Event Callbacks

Source: https://context7.com/nmvteam/nightmarevision/llms.txt

Callbacks for handling chart events, allowing preprocessing, asset preloading, and reaction logic. Can offset event timing or trigger game actions.

```haxe
function eventEarlyTrigger(name:String, value1:String, value2:String):Int {
    // Return milliseconds early to offset event timing
    if (name == "My Custom Event") return -100; // trigger 100ms early
    return 0;
}

function onEventPush(event) {
    // Called when the chart is first read — good for preloading assets
    if (event.name == "Play Cutscene")
        FlxG.bitmap.add(Paths.image("cutscene/frame1"));
}

function onFirstPush(event) {
    // Only fires the first time a particular event name appears in the chart
    trace("First occurrence of: " + event.name);
}

function onEvent(name:String, value1:String, value2:String) {
    switch (name) {
        case "Flash Screen":
            FlxG.camera.flash(FlxColor.WHITE, 0.3);
        case "Shake Camera":
            FlxG.camera.shake(0.02, Std.parseFloat(value1));
        default:
            // unhandled events fall through silently
    }
}
```

--------------------------------

### Note Skin JSON Definition

Source: https://context7.com/nmvteam/nightmarevision/llms.txt

Defines textures, animations, and scaling for note receptors and splashes. Used in `data/noteskins/<name>.json`.

```json
{
    "noteTexture":    "UI/notes/NOTE_assets",
    "splashTexture":  "UI/notes/noteSplashes",
    "antialiasing":   true,
    "inGameColoring": true,
    "noteScale":      0.7,
    "splashScale":    1.5,
    "splashesEnabled": true,

    "receptorAnimations": [
        [
            { "anim": "static",   "xmlName": "arrowLEFT",   "looping": false, "offsets": [0, 0] },
            { "anim": "pressed",  "xmlName": "left press",   "looping": false, "offsets": [0, 0] },
            { "anim": "confirm",  "xmlName": "left confirm", "looping": false, "offsets": [-1, -1] }
        ]
        // ... repeat for DOWN, UP, RIGHT
    ],

    "noteAnimations": [
        [
            { "anim": "scroll",  "xmlName": "purple",            "looping": false, "offsets": [0, 0] },
            { "anim": "hold",    "xmlName": "purple hold piece", "looping": false, "offsets": [0, 0] },
            { "anim": "holdend", "xmlName": "purple hold end",   "looping": false, "offsets": [0, 0] }
        ]
        // ... repeat for blue (DOWN), green (UP), red (RIGHT)
    ],

    "singAnimations": ["singLEFT", "singDOWN", "singUP", "singRIGHT"]
}
```

--------------------------------

### Mod Metadata Configuration (`meta.json`)

Source: https://context7.com/nmvteam/nightmarevision/llms.txt

Configures engine-level properties for a mod, including display name, Discord Rich Presence ID, window title, and asset prefixes. This file is optional but recommended for defining mod identity and behavior.

```json
{
    "name": "Friday Night Funkin: D-Sides (REDUX)",
    "description": "The iconic remix mod of Friday Night Funkin'!",
    "global": false,

    "discordClientID": "960620410095956018",
    "windowTitle": "Friday Night Funkin: D-Sides",
    "iconFile": "UI/window/icons/64",
    "defaultTransition": "SimpleSticker",
    "defaultFont": "vcr.ttf",

    "uiPrefix": "UI/game/HUD/",
    "countdownPrefix": "UI/game/HUD/countdown/",
    "ratingsPrefix": "UI/game/HUD/ratings/",
    "comboPrefix": "UI/game/HUD/combo/",

    "stateRedirects": {
        "TitleState":     "TitleState",
        "MainMenuState":  "MainMenuState",
        "StoryMenuState": "StoryMenuState",
        "FreeplayState":  "FreeplayState",
        "CreditsState":   "Credits",
        "OptionsState":   "Options"
    }
}
```

--------------------------------

### Input Functions

Source: https://github.com/nmvteam/nightmarevision/wiki/3.-Scripting

Functions that are triggered by player input events, applicable to every PlayState script.

```APIDOC
## onGhostTap(key)

### Description
Function is run when the player presses a `StrumNote` without any notes being hit.

### Fields
- `key` (FlxKey) - The `FlxKey` value corresponding to the key just pressed.
```

```APIDOC
## noteMissPress(key)

### Description
Function is run when the player presses a `StrumNote` without any notes being hit, with the ghost tapping setting disabled.

### Fields
- `key` (FlxKey) - The `FlxKey` value corresponding to the key just pressed.
```

```APIDOC
## onKeyPress(key)

### Description
Function is run when the player presses a key.

### Fields
- `key` (FlxKey) - The `FlxKey` value corresponding to the key just pressed.
```

```APIDOC
## onKeyRelease(key)

### Description
Function is run when the player releases a previously pressed key.

### Fields
- `key` (FlxKey) - The `FlxKey` value corresponding to the key just pressed.
```

--------------------------------

### Freeplay Menu Song Grouping (`freeplay.json`)

Source: https://context7.com/nmvteam/nightmarevision/llms.txt

Defines tabbed groups of songs for the Freeplay menu. Tabs can reference songs from week JSON files or list song folder names directly. If absent, the engine reads the `weeks/` folder automatically.

```json
{
    "tabs": [
        {
            "title": "Friday Night Funkin'",
            "fromWeeks": ["tutorial", "week1", "week1-pico", "week2", "week3", "week4", "week5", "week6", "week7"]
        },
        {
            "title": "Erect Mixes",
            "songs": ["Bopeebo-erect", "Fresh-erect", "Dadbattle-erect"]
        },
        {
            "title": "Pico Mixes",
            "songs": [
                "Bopeebo (Pico Mix)", "Fresh (Pico Mix)", "DadBattle (Pico Mix)",
                "Stress (Pico Mix)", "Darnell", "Lit-Up", "2hot", "Blazin"
            ]
        }
    ]
}
```

--------------------------------

### Note Functions

Source: https://github.com/nmvteam/nightmarevision/wiki/3.-Scripting

Functions that are triggered by various note-related events during gameplay.

```APIDOC
## onSpawnNote(note)

### Description
Function is run before a `Note` object is created via the song chart being read.

### Fields
- `note` (Note object) - The note object to be created.

### Return Value
- If `ScriptConstants.STOP_FUNC` is returned, the note will not be spawned.
```

```APIDOC
## onSpawnNotePost(note)

### Description
Function is run after a `Note` object is created via the song chart being read.

### Fields
- `note` (Note object) - The note object to be created.
```

```APIDOC
## noteMiss(note)

### Description
Function is run when the player misses a note.

### Fields
- `note` (Note object) - The `Note` object that the player failed to press.
```

```APIDOC
## noteMissPress(key)

### Description
Function is run when the player presses a `StrumNote` without any notes being hit and their Ghost Tapping setting is disabled.

### Fields
- `key` (FlxKey) - The `FlxKey` value corresponding to the key just pressed.
```

```APIDOC
## goodNoteHitPre(note)

### Description
Function is run when the player presses a note, but before any `PlayState` functionality runs.

### Fields
- `note` (Note object) - The `Note` object that the player pressed.
```

```APIDOC
## opponentNoteHitPre(note)

### Description
Function is run when the opponent hits a note, but before any `PlayState` functionality runs.

### Fields
- `note` (Note object) - The `Note` object that the opponent hit.
```

```APIDOC
## extraNoteHitPre(note)

### Description
Function is run when any strumline with an ID above 1 hits a note, but before any `PlayState` functionality runs.

### Fields
- `note` (Note object) - The `Note` object that the strum pressed.
```

```APIDOC
## onGhostAnim(anim, note)

### Description
Function is run if the character who hit a note play's a double-note ghost effect.

### Fields
- `anim` (string) - The string value of the animation the ghost is playing.
- `note` (Note object) - The `Note` object corresponding to the note the character just hit.

### Return Value
- If `ScriptConstants.STOP_FUNC` is returned, the character will not play a ghost note.
```

```APIDOC
## goodNoteHit(note)

### Description
Function is run when the player hits a note, after all `PlayState` functionality has run.

### Fields
- `note` (Note object) - The `Note` object the player just hit.
```

```APIDOC
## opponentNoteHit(note)

### Description
Function is run when the opponent hits a note, after all `PlayState` functionality has run.

### Fields
- `note` (Note object) - The `Note` object the opponent just hit.
```

```APIDOC
## extraNoteHit(note)

### Description
Function is run when the strumline with an ID above 0 or 1 hits a note, after all `PlayState` functionality has run.

### Fields
- `note` (Note object) - The `Note` object the strumline just hit.
```

```APIDOC
## onSpawnNoteSplash(splash, note)

### Description
Function is run when a `NoteSplash` object is spawned on the player's receptors.

### Fields
- `splash` (NoteSplash object) - The `NoteSplash` object that has been spawned.
- `note` (Note object) - The `Note` object that caused the `NoteSplash` to spawn.
```

--------------------------------

### HScript Lifecycle Callbacks

Source: https://context7.com/nmvteam/nightmarevision/llms.txt

Global functions available in HScript for controlling game logic and responding to events. Return `ScriptConstants.STOP_FUNC` to override default behavior.

```haxe
// scripts/MyPlayStateScript.hx

function onLoad() {
    // Runs immediately when the script is loaded — safe for pre-create setup
    trace("Script loaded!");
}

function onCreatePost() {
    // Runs after super.create() — safe to reference all FlxState objects
    FlxG.camera.zoom = 0.85;
}

function onUpdate(elapsed:Float) {
    // Runs every frame; elapsed is seconds since last frame
    if (FlxG.keys.justPressed.R)
        trace("R pressed at " + elapsed);
}

function onBeatHit() {
    // Fires every beat — requires Conductor to be set up
    trace("Beat: " + curBeat);
}

function onStepHit() {
    // Fires every step (quarter-beat)
}

function onSectionHit() {
    // Fires every chart section
}

function onDestroy() {
    // Clean up any resources allocated in this script
}
```

--------------------------------

### Event Functions

Source: https://github.com/nmvteam/nightmarevision/wiki/3.-Scripting

Functions that are triggered by charted events within the game.

```APIDOC
## eventEarlyTrigger(name, value1, value2)

### Description
Function is run for every charted event. Meant for getting early / delayed timing of specific events.

### Fields
- `name` (string) - The targeted event's name.
- `value1` (any) - The targeted event's first value.
- `value2` (any) - The targeted event's second value.

### Return Value
Returns the integer value of how many milliseconds early your event should be triggered.
```

```APIDOC
## onEventPush(event)

### Description
Function is run when the event-note is registered when the chart is read. Typically used for creating / loading assets.

### Fields
- `event` (EventNote) - The `EventNote` object created upon read. Values are readable by calling `event.name`, `event.value1`, `event.value2`.
```

```APIDOC
## onFirstPush(event)

### Description
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.

### Fields
- `event` (EventNote) - The `EventNote` object created upon read. Values are readable by calling `event.name`, `event.value1`, `event.value2`.
```

```APIDOC
## onEvent(name, value1, value2)

### Description
Function is run every time a charted event occurs.

### Fields
- `name` (string) - The targeted event's name.
- `value1` (any) - The targeted event's first value.
- `value2` (any) - The targeted event's second value.
```

--------------------------------

### Song-related Functions

Source: https://github.com/nmvteam/nightmarevision/wiki/3.-Scripting

Functions that are triggered by events related to the song's playback and progression.

```APIDOC
## onStartCountdown()

### Description
Function is run whenever the pre-song Countdown begins. If the countdown is skipped, it will run immediately as the song starts.

### Return Value
If `ScriptConstants.STOP_FUNC` is returned, the function will not run and the song will not start.
```

```APIDOC
## onCountdownTick(tick)

### Description
Function is run on each count of the countdown. Run four times sequentially on-beat with the song.

### Fields
- `tick` (integer) - The current countdown's tick, starting at 0 and ending at 3.
```

```APIDOC
## onSongStart()

### Description
Function is run when the song begins.
```

```APIDOC
## onEndSong()

### Description
Function is run when the song completes.

### Return Value
If `ScriptConstants.STOP_FUNC` is returned, `PlayState`'s end-song functions will not run.
```

```APIDOC
## onPause()

### Description
Function is run when the player pauses the song.

### Return Value
If `ScriptConstants.STOP_FUNC` is returned, the pause menu will not open.
```

```APIDOC
## onResume()

### Description
Function is run when the player resumes the song after pausing.
```

```APIDOC
## onGameOver()

### Description
Function is run when the player runs out of health and dies.

### Return Value
If `ScriptConstants.STOP_FUNC` is returned, `PlayState`s game-over functions will not run.
```

```APIDOC
## onMoveCamera(focus)

### Description
Function is run whenever the in-game camera moves to focus on another character.

### Fields
- `focus` (string) - The currently-focused character. Possible values: "boyfriend", "dad", "gf".
```

--------------------------------

### Stage JSON Definition

Source: https://context7.com/nmvteam/nightmarevision/llms.txt

Sets camera zoom, character positions, z-ordering, and background objects for a stage. Used in `data/stages/<stage>/data.json`.

```json
{
    "defaultZoom": 0.9,
    "isPixelStage": false,
    "boyfriend":  [770, 100],
    "girlfriend": [400, 130],
    "opponent":   [100, 100],
    "hide_girlfriend": false,
    "camera_boyfriend": [0, 0],
    "camera_opponent":  [0, 0],
    "camera_girlfriend":[0, 0],
    "camera_speed": 1,
    "dadZIndex": 3,
    "bfZIndex":  3,
    "gfZIndex":  3,
    "stageObjects": [
        { "id": "bg",    "asset": "stageback",    "position": [-600, -200], "zIndex": 1 },
        { "id": "front", "asset": "stagefront",   "position": [-600,  600], "zIndex": 2 },
        {                "asset": "stagecurtains","position": [-600, -300], "zIndex": 9999,
          "scrollFactor": [1.1, 1.1] }
    ]
}
```

--------------------------------

### Nightmare Vision Mod Folder Structure

Source: https://github.com/nmvteam/nightmarevision/wiki/1.-Features-&-Improvements-(WIP)

This is the reorganized mod folder structure for Nightmare Vision. It offers a more concise organization for assets, separating audio and charts within song folders.

```plaintext
YourMod
├── data
│   ├── events
│   ├── noteskins
│   ├── notetypes
│   └── weeks
├── images
│   └── ui
│       └── icons
├── scripts
│   ├── states
│   └── substates
├── songs
│   └── your-song
│       ├── audio
│       └── charts
└── stages
    └── your-stage
```

--------------------------------

### Psych Engine Mod Folder Structure

Source: https://github.com/nmvteam/nightmarevision/wiki/1.-Features-&-Improvements-(WIP)

This is the typical mod folder structure for Psych Engine. It organizes assets like characters, songs, scripts, and stages.

```plaintext
YourMod
├── characters
├── custom_events
├── custom_notetypes
├── data
│   ├── your-song(json)
├── images
│   └── icons
├── scripts
├── songs
│   └── your-song(ogg)
└── stages
    └── your-stage.lua
    └── your-stage.json
└── weeks
```

--------------------------------

### Character JSON Definition

Source: https://context7.com/nmvteam/nightmarevision/llms.txt

Defines character sprites, animations, offsets, and health bar colors. Used in `data/characters/<name>.json`.

```json
{
    "image": "characters/BOYFRIEND",
    "scale": 1,
    "flip_x": true,
    "no_antialiasing": false,
    "position": [0, 350],
    "camera_position": [0, 0],
    "healthicon": "bf",
    "healthbar_colors": [49, 176, 209],
    "sing_duration": 4,
    "animations": [
        { "anim": "idle",       "name": "BF idle dance",    "fps": 24, "loop": false, "indices": [], "offsets": [-5, 0] },
        { "anim": "singLEFT",   "name": "BF NOTE LEFT0",    "fps": 24, "loop": false, "indices": [], "offsets": [5, -6] },
        { "anim": "singDOWN",   "name": "BF NOTE DOWN0",    "fps": 24, "loop": false, "indices": [], "offsets": [-20, -51] },
        { "anim": "singUP",     "name": "BF NOTE UP0",      "fps": 24, "loop": false, "indices": [], "offsets": [-46, 27] },
        { "anim": "singRIGHT",  "name": "BF NOTE RIGHT0",   "fps": 24, "loop": false, "indices": [], "offsets": [-48, -7] },
        { "anim": "singLEFTmiss",  "name": "BF NOTE LEFT MISS",  "fps": 24, "loop": false, "indices": [], "offsets": [7, 19] },
        { "anim": "singDOWNmiss",  "name": "BF NOTE DOWN MISS",  "fps": 24, "loop": false, "indices": [], "offsets": [-15, -19] },
        { "anim": "hurt",       "name": "BF hit",           "fps": 24, "loop": false, "indices": [], "offsets": [14, 18] }
    ]
}
```

--------------------------------

### HUD Functions

Source: https://github.com/nmvteam/nightmarevision/wiki/3.-Scripting

Functions that are triggered by updates to the Heads-Up Display (HUD) elements.

```APIDOC
## onPopUpScore(note, rating, ratingGraphic, ratingNumGroup)

### Description
Function is run when the player hits a note and the ratings/combo graphics appear on screen.

### Fields
- `note` (Note object) - The `Note` object that the player pressed.
- `rating` (Rating data class) - The `Rating` data class that the pop up reads from.
- `ratingGraphic` (FlxSprite) - The `FlxSprite` graphic of the rating graphic displayed on screen, such as "Sick!" or "shit".
- `ratingNumGroup` (FlxTypedGroup) - The `FlxTypedGroup` of `FlxSprite` graphics that display the player's current combo.
```

```APIDOC
## onPopUpScorePost(note, rating, ratingGraphic, ratingNumGroup)

### Description
Function is run after the player hits a note and the ratings/combo graphics appear on screen.

### Fields
- `note` (Note object) - The `Note` object that the player pressed.
- `rating` (Rating data class) - The `Rating` data class that the pop up reads from.
- `ratingGraphic` (FlxSprite) - The `FlxSprite` graphic of the rating graphic displayed on screen, such as "Sick!" or "shit".
- `ratingNumGroup` (FlxTypedGroup) - The `FlxTypedGroup` of `FlxSprite` graphics that display the player's current combo.
```

```APIDOC
## onUpdateScore(miss)

### Description
Function is run whenever the score values are updated on the HUD object `scoreTxt`.

### Fields
- `miss` (Boolean) - A Boolean value that says if the recently-hit note was hit with a high enough accuracy or not.

### Return Value
- If `ScriptConstants.STOP_FUNC` is returned, the HUD object `scoreTxt` will not have its text values updated.
```

```APIDOC
## onRecalculateRating()

### Description
Function is run when the player's current rank / accuracy is being calculated.

### Fields
- None.
```

--------------------------------

### Queue Modifier Value Change

Source: https://github.com/nmvteam/nightmarevision/wiki/5.-Modcharts-&-Modifiers-(WIP)

Queue a modifier value change to occur at a specific step. This is useful for timed events. The player argument determines if the change applies to the player, opponent, or both.

```javascript
modManager.queueSet(32, "drunk", 1, 0);
```

--------------------------------

### Set Modifier Value

Source: https://github.com/nmvteam/nightmarevision/wiki/5.-Modcharts-&-Modifiers-(WIP)

Use this function to immediately set a modifier's value for a specific player or both. Ensure the modName, val, and player arguments are correctly provided.

```javascript
modManager.setValue("drunk", 1, 0);
```

--------------------------------

### ModManager Functions

Source: https://github.com/nmvteam/nightmarevision/wiki/5.-Modcharts-&-Modifiers-(WIP)

Functions available in the ModManager class to control modifier values. These can be called from a PlayState script.

```APIDOC
## setValue

### Description
Sets a modifier to a specific value for a given player.

### Method
`setValue(modName:String, val:Float, player:Int)`

### Parameters
- **modName** (String) - The name of the modifier to change.
- **val** (Float) - The value to set the modifier to.
- **player** (Int) - The player strumline to apply the value to (0 for player, 1 for opponent, -1 or omitted for both).

### Example
```javascript
modManager.setValue("drunk", 1, 0);
```
```

```APIDOC
## queueSet

### Description
Queues a modifier to be set to a specific value at a given song step.

### Method
`queueSet(step:Float, modName:String, target:Float, player:Int)`

### Parameters
- **step** (Float) - The song step at which to change the modifier value.
- **modName** (String) - The name of the modifier to change.
- **target** (Float) - The value to set the modifier to.
- **player** (Int) - The player strumline to apply the value to (0 for player, 1 for opponent, -1 or omitted for both).

### Example
```javascript
modManager.queueSet(32, "drunk", 1, 0);
```
```

```APIDOC
## queueEase

### Description
Queues a modifier to smoothly transition its value to a target value over a specified range of song steps, using a defined easing style.

### Method
`queueEase(step:Float, endStep:Float, modName:String, target:Float, style:String = 'linear', player:Int = -1, ?startVal:Float)`

### Parameters
- **step** (Float) - The song step at which to start the eased value change.
- **endStep** (Float) - The song step at which to end the eased value change.
- **modName** (String) - The name of the modifier to change.
- **target** (Float) - The value to ease the modifier to.
- **style** (String) - The type of easing to use (e.g., 'linear', 'bounceOut'). Defaults to 'linear'.
- **player** (Int) - The player strumline to apply the value to (0 for player, 1 for opponent, -1 or omitted for both). Defaults to -1 (both).
- **startVal** (Float) - Optional. The starting value for the ease.

### Example
```javascript
modManager.queueEase(16, 32, "squish", 1, "bounceOut", 0);
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.