### Switch to PlayState

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/playstate-api.md

Examples of initializing and switching to PlayState for Freeplay and Story modes.

```haxe
// Freeplay mode with single song
var state = new PlayState(FREEPLAY, ['weekend'], 'hard');
FlxG.switchState(state);

// Story mode with week and multiple songs
var state = new PlayState(STORY, ['bopeebo', 'fresh', 'dadbattle'], 'normal', 'week1', 0, 0);
FlxG.switchState(state);
```

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

### new(newType, newPlaylist, newDifficulty, newWeek, newWeekScore, newSongIndex)

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/playstate-api.md

Initializes a new PlayState instance to start a gameplay session.

```APIDOC
## Constructor

### Description
Initializes a new PlayState instance. This constructor sets up the game mode, playlist, difficulty, and initial scoring context.

### Signature
`public function new(?newType:SongType, ?newPlaylist:Array<String>, ?newDifficulty:String, ?newWeek:String, ?newWeekScore:Float, ?newSongIndex:Int):Void`

### Parameters
- **newType** (SongType) - Optional - FREEPLAY or STORY mode (Default: FREEPLAY)
- **newPlaylist** (Array<String>) - Optional - Songs to play in sequence (Default: ['bopeebo'])
- **newDifficulty** (String) - Optional - Difficulty identifier (Default: 'normal')
- **newWeek** (String) - Optional - Week ID for story mode (Default: null)
- **newWeekScore** (Float) - Optional - Cumulative week score (Default: 0)
- **newSongIndex** (Int) - Optional - Index in playlist (Default: 0)
```

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

### Example HScript Implementation

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/configuration.md

Demonstrates a custom state script using HScript syntax. This script initializes a state and modifies playState speed on specific beats.

```haxe
// scripts/custom-state.hscript
function new() {
    trace("State initialized");
}

function beatHit(curBeat:Int) {
    if (curBeat % 4 == 0) {
        playState.speed = 1.5;
    }
}
```

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

### Get Stage Configuration

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/core-classes-api.md

Loads and converts stage configuration data.

```haxe
var stage = Formatter.getStage('stage-main');
```

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

### Conductor.play

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/core-classes-api.md

Starts music playback with optional start time and looping configuration.

```APIDOC
## Conductor.play(?time:Float, ?looped:Bool):Void

### Description
Starts music playback. Can specify a start time in milliseconds and whether the track should loop.

### Parameters
- **time** (Float) - Optional - Start time in ms (default: 0)
- **looped** (Bool) - Optional - Whether music loops (default: false)
```

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

### Get Song Chart

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/core-classes-api.md

Loads and converts a song chart to the ALESong format.

```haxe
var chart = Formatter.getChart('bopeebo', 'normal');
```

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

### Get Character Configuration

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/core-classes-api.md

Loads and converts character configuration data.

```haxe
var bf = Formatter.getCharacter('bf', PLAYER);
```

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

### Generic Haxe Code Example Placeholder

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/README.md

Placeholder used in the documentation template to indicate where code examples should be placed.

```haxe
// Code example
```

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

### Initialize HScript

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/configuration.md

Initializes the HScript runtime environment. This method handles macro loading, import configuration, and preset setup.

```haxe
public static function init():Void
{
    // Load macros
    // Configure imports
    // Setup presets
}
```

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

### Get HUD Configuration

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/core-classes-api.md

Loads HUD configuration data.

```haxe
var hud = Formatter.getHud('default');
```

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

### Get Image Path

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/core-classes-api.md

Retrieves the full path for an image asset.

```haxe
var path = Paths.image('menu/bg');
```

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

### Play Music

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/core-classes-api.md

Starts music playback at a specific time, with optional looping enabled.

```haxe
Conductor.play();                // Start from beginning
Conductor.play(1000);            // Start at 1 second (1000ms)
Conductor.play(5000, true);      // Start at 5s with looping
```

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

### Haxe Method Signature Template

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/README.md

Example of the Haxe method signature format used within the documentation template.

```haxe
public function methodName(param:Type):ReturnType
```

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

### characterFromNote(note:Note)

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/playstate-api.md

Gets the character for a note's strumline.

```APIDOC
## characterFromNote(note:Note)

### Description
Get the character for a note's strumline.

### Parameters
- **note** (Note) - Required - Note object
```

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

### Create Custom Splash Effect

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/gameplay-systems.md

Example of spawning a custom splash effect during a note hit in a Lua script.

```lua
-- In PlayState script
function hitNote(note, timeDistance, removeNote)
    if timeDistance < 50 then
        -- Perfect hit - use special splash
        makeLuaSprite('perfect_splash', 'effects/perfect', note.x, note.y)
        playAnim('perfect_splash', 'burst')
        addLuaSprite('perfect_splash')
    end
end
```

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

### Get Song BPM in Lua

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/lua-scripting.md

Retrieves the current song beats per minute.

```lua
local bpm = getBPM()
print("Current BPM: " .. bpm)
```

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

### Get Current Step Index in Lua

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/lua-scripting.md

Retrieves the current step number.

```lua
local step = getCurrentStep()
```

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

### Get Character Camera

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/playstate-api.md

Returns the camera focus point for a given character.

```haxe
function getCharacterCamera(character:Character):Point
```

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

### Get File Directory

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/lua-scripting.md

Extracts the directory path from a full file path string.

```lua
local dir = getFileDirectory('data/test/file.json')
-- Returns: 'data/test'
```

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

### Documentation Markdown Template

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/README.md

Standard template used for all source file documentation. Includes sections for signatures, parameters, return types, and code examples.

```markdown
# Top-Level Heading (File Title)

## Section Heading

### Subsection (usually method/class)

**File**: source/path/File.hx
**Type**: class/interface/typedef
**Purpose**: One-line description

### Signature
```haxe
public function methodName(param:Type):ReturnType
```

### Parameters
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| name | type | default | description |

### Returns
**Type** — description

### Example
```haxe
// Code example
```
```

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

### Get Song Playback Time in Lua

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/lua-scripting.md

Retrieves the current song playback time in milliseconds.

```lua
local time = getTime()  -- In milliseconds
```

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

### Initialize Lua Environment

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/configuration.md

Sets up the Lua environment by loading standard library callbacks and registering object accessors.

```haxe
public function new(lua:LuaScript):Void
{
    // Load all standard library callbacks
    // Set up preset functions
    // Register object accessors
}
```

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

### Play Sprite Animation

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/core-classes-api.md

Triggers an animation by name with optional parameters for forcing, reversing, or setting the start frame.

```haxe
sprite.playAnim('idle', true);
sprite.playAnim('walk', false, true);  // Play reversed
```

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

### Manage Audio

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/playstate-api.md

Methods for initializing audio systems and synchronizing vocal tracks.

```haxe
function initSounds():Void
```

```haxe
function addVocal(sound:Sound):Void
```

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

### Initialize Stage

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/core-classes-api.md

Constructor signature for creating a new Stage instance.

```haxe
public function new(initial:JsonStage, ?parent:Dynamic):Void
```

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

### Hit Note

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/playstate-api.md

Processes a player note hit. Use the example for manual hit handling in advanced scripts.

```haxe
function hitNote(note:Note, timeDistance:Float, removeNote:Bool):Bool
```

```haxe
// Manual note hit (advanced scripting)
var rating = playState.judgeNote(timeDistance);
playState.hitNote(note, timeDistance, true);
```

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

### Initialize Game Window

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/configuration.md

Sets the initial resolution and frame rate for the game state.

```haxe
// In Game class
super(1280, 720, MainState, 120, 120, true, false);
```

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

### Paths.init()

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/core-classes-api.md

Initializes the asset path system and cache.

```APIDOC
## Paths.init()

### Description
Initializes asset paths and cache.

### Signature
`public static function init():Void`
```

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

### getCharacterCamera(character:Character)

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/playstate-api.md

Gets camera focus point for a character.

```APIDOC
## getCharacterCamera(character:Character)

### Description
Get camera focus point for a character.

### Parameters
- **character** (Character) - Required - Character instance

### Returns
- **Point** - Camera position {x, y}
```

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

### Initialize Paths

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/core-classes-api.md

Initializes asset paths and the internal cache.

```haxe
Paths.init();
```

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

### Initialize Camera object

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/core-classes-api.md

Constructor for creating a new game viewport.

```haxe
public function new(?x:Float, ?y:Float, ?width:Int, ?height:Int, ?zoom:Float):Void
```

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

### Initialize Characters

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/playstate-api.md

Creates all characters based on stage and strumline configuration.

```haxe
function initCharacters():Void
```

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

### Initialize Note Constructor

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/gameplay-systems.md

Defines the signature for creating a new Note instance.

```haxe
public function new(
    id:String,
    strlData:JsonStrumLineConfig,
    type:NoteType,
    data:Int,
    rgb:RGBShader
):Void
```

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

### Get Current Section Index in Lua

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/lua-scripting.md

Retrieves the current section number.

```lua
local section = getCurrentSection()
```

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

### Initialize PlayState

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/playstate-api.md

Constructor signature for creating a new PlayState instance.

```haxe
public function new(
    ?newType:SongType,
    ?newPlaylist:Array<String>,
    ?newDifficulty:String,
    ?newWeek:String,
    ?newWeekScore:Float,
    ?newSongIndex:Int
):Void
```

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

### Initialize Script Presets

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/configuration.md

Instantiates base preset classes to load default functions into script environments.

```haxe
// Lua presets
new LuaPreset(script);  // Loads all default Lua functions

// HScript presets
new HScriptPresetBase(script);
```

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

### Get Current Beat Index in Lua

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/lua-scripting.md

Retrieves the current beat number.

```lua
local beat = getCurrentBeat()
```

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

### Get Step Duration in Lua

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/lua-scripting.md

Retrieves the duration of a single step in milliseconds.

```lua
local stepDuration = getStepCrochet()
```

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

### Initialize Strumlines

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/playstate-api.md

Initializes player and opponent strumlines based on chart configuration.

```haxe
function initStrumLines():Void
```

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

### CoolUtil.openSubState

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/core-classes-api.md

Open a game substate with optional arguments.

```APIDOC
## CoolUtil.openSubState(subState:Class<FlxSubState>, ?args:Array<Dynamic>)

### Description
Open a substate.

### Parameters
- **subState** (Class<FlxSubState>) - Required - SubState class.
- **args** (Array<Dynamic>) - Optional - Arguments for constructor.
```

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

### Get Beat Duration in Lua

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/lua-scripting.md

Retrieves the duration of a single beat in milliseconds.

```lua
local beatDuration = getCrochet()  -- In milliseconds
```

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

### Get Sprite Midpoint Y

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/lua-scripting.md

Returns the vertical center coordinate of the specified sprite.

```lua
local midY = getMidpointY('mySprite')
```

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

### initStrumLines()

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/playstate-api.md

Initializes player and opponent strumlines based on chart configuration.

```APIDOC
## initStrumLines()

### Description
Create note lanes from chart configuration. Initializes player strumlines and opponent strumlines.

### Signature
`function initStrumLines():Void`
```

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

### new StrumLine(config:JsonStrumLineConfig)

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/gameplay-systems.md

Initializes a new StrumLine instance with the provided configuration.

```APIDOC
## Constructor

### Description
Creates a new StrumLine instance to manage a set of note lanes.

### Signature
`public function new(config:JsonStrumLineConfig):Void`

### Parameters
- **config** (JsonStrumLineConfig) - Required - Strum line configuration object containing ID, animation names, type, direction, and position.
```

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

### Get sprite properties

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/lua-scripting.md

Retrieves the current value of a specific property from a sprite.

```lua
local x = getProperty('mySprite', 'x')
local visible = getProperty('mySprite', 'visible')
```

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

### Initialize StrumLine Constructor

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/gameplay-systems.md

Constructor for creating a new StrumLine instance using a configuration object.

```haxe
public function new(config:JsonStrumLineConfig):Void
```

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

### Initialize Icon Constructor

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/gameplay-systems.md

Defines the constructor signature for the Icon class.

```haxe
public function new(id:String):Void
```

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

### Create a simple state script in Lua

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/lua-scripting.md

Initializes sprites and text, and handles frame-based updates and beat-synced animations.

```lua
-- scripts/states/custom-state.lua
function new()
    print("State initialized")
    
    -- Create background sprite
    makeLuaSprite('bg', 'menu/bg', 0, 0)
    addLuaSprite('bg')
    
    -- Create text
    makeLuaText('title', 'Welcome!', 0, 100, 50)
    addLuaText('title')
end

function update(elapsed)
    -- Update every frame
    setProperty('title', 'angle', getProperty('title', 'angle') + 45 * elapsed)
end

function beatHit(curBeat)
    if curBeat % 2 == 0 then
        doTweenScale('title', 'scale', 1.2, 0.5, 'quadOut')
    end
end
```

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

### Get Sprite Midpoint X

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/lua-scripting.md

Returns the horizontal center coordinate of the specified sprite.

```lua
local midX = getMidpointX('mySprite')
```

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

### Load a Song in Haxe

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/INDEX.md

Initializes a chart and switches the game state to PlayState.

```haxe
var chart = Formatter.getChart('bopeebo', 'normal');
var state = new PlayState(FREEPLAY, ['bopeebo'], 'normal');
FlxG.switchState(state);
```

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

### Get Character from Note

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/playstate-api.md

Retrieves the character associated with a specific note's strumline.

```haxe
function characterFromNote(note:Note):Void
```

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

### Initialize StrumLine in Haxe

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/core-classes-api.md

Constructor signature for creating a new StrumLine instance.

```haxe
public function new(config:JsonStrumLine):Void
```

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

### Open SubState

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/core-classes-api.md

Opens a substate, optionally passing arguments to the constructor.

```haxe
CoolUtil.openSubState(PauseSubState);
CoolUtil.openSubState(CustomSubState, ['myData', 123]);
```

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

### Get sprite scale

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/lua-scripting.md

Returns the current scale of a sprite as a table containing x and y values.

```lua
local scale = getScale('mySprite')
print(scale.x, scale.y)
```

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

### Create a sprite from JSON

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/lua-scripting.md

Initializes a sprite using a configuration table and a specified asset directory.

```lua
local data = {
    images = {'character'},
    animations = {...}
}
makeLuaFunkinSprite('char', data, 'characters/')
```

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

### Create a stage script in Lua

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/lua-scripting.md

Manages stage sprite initialization and periodic scaling animations based on beat and step hits.

```lua
-- scripts/stages/stage-id.lua
local bopTimer = 0

function new()
    makeLuaSprite('stage', 'stage/bg', 0, 0)
    addLuaSprite('stage')
end

function beatHit(curBeat)
    bopTimer = 0
    doTweenScale('stage', 'scale', 1.1, 0.2, 'linear')
end

function stepHit(curStep)
    bopTimer = bopTimer + 1
    if bopTimer > 8 then
        bopTimer = 0
        doTweenScale('stage', 'scale', 1.0, 0.5, 'elastic')
    end
end
```

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

### Song and Chart Management Methods

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/playstate-api.md

Methods for initializing songs, managing countdowns, and handling event triggers.

```haxe
function initSong():Void
```

```haxe
function startCountdown():Void
```

```haxe
// Start countdown after 1 second
FlxTimer.wait(1, (_) -> playState.startCountdown());
```

```haxe
function startSong():Void
```

```haxe
function initEvents():Void
```

```haxe
function stackEventList(eventList:ALEEventList):Void
```

```haxe
function eventHit(event:ALEEvent):Void
```

```lua
-- In a Lua script attached to PlayState
function eventHit(event)
    if event.id == 'myCustomEvent' then
        print("Custom event triggered with values:", table.unpack(event.values))
    end
end
```

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

### Configure Beat Hit Animations

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/core-classes-api.md

Initialize automatic animations synchronized to the beat.

```haxe
bopper.configBeatHitAnimations();
```

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

### StrumLine.new(config:JsonStrumLine):Void

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/core-classes-api.md

Constructor for creating a new StrumLine instance.

```APIDOC
## new(config:JsonStrumLine):Void

### Description
Initializes a new StrumLine instance with the provided configuration.

### Parameters
- **config** (JsonStrumLine) - Required - Strum line configuration data.
```

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

### Get Sprite Pixel Color

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/lua-scripting.md

Retrieves the color value of a specific pixel at the given coordinates in AARRGGBB format.

```lua
local color = getPixelColor('mySprite', 10, 10)
print(string.format('0x%08X', color))
```

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

### Initialize VideoSprite

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/core-classes-api.md

Constructor for creating a new VideoSprite instance using a video path without an extension.

```haxe
public function new(video:String):Void
```

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

### Implement and Register Plugin

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/configuration.md

Extends FlxBasic to create custom plugins and registers them via the PluginsHandler.

```haxe
// Create custom plugin
class MyPlugin extends FlxBasic {
    override function update(elapsed:Float) {
        // Plugin logic
    }
}

// Register plugin
PluginsHandler.add(new MyPlugin());
```

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

### new(id:String, strlData:JsonStrumLineConfig, type:NoteType, data:Int, rgb:RGBShader):Void

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/gameplay-systems.md

Constructor for creating a new Note instance.

```APIDOC
## Constructor: new(id, strlData, type, data, rgb)

### Description
Initializes a new Note instance with the specified configuration, type, lane, and shader.

### Parameters
- **id** (String) - Note skin ID
- **strlData** (JsonStrumLineConfig) - Strum line configuration
- **type** (NoteType) - ARROW, SUSTAIN, or END
- **data** (Int) - Note lane (0-3 typically)
- **rgb** (RGBShader) - RGB color shader
```

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

### Lifecycle Methods

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/playstate-api.md

Standard Haxe lifecycle methods for state initialization, frame updates, and memory cleanup.

```haxe
override function create():Void
```

```haxe
override function destroy():Void
```

```haxe
override function update(elapsed:Float):Void
```

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

### Create a basic sprite

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/lua-scripting.md

Initializes a new sprite using an image path and adds it to the scene.

```lua
makeLuaSprite('bg', 'stage/stage-bg', 0, 0)
addLuaSprite('bg')
```

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

### Initialize Character

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/core-classes-api.md

Create a new character instance by specifying the ID and role type.

```haxe
var bf = new Character('bf', PLAYER);
var dad = new Character('dad', OPPONENT);
```

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

### Initialize Formatter

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/core-classes-api.md

Initializes all format converters. Must be called before accessing conversion methods.

```haxe
Formatter.init();
```

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

### Manage Client Preferences in Haxe

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/configuration.md

Initializes, modifies, and persists client preferences to disk.

```haxe
ClientPrefs.init();  // Load from disk

ClientPrefs.data.volume = 0.8;
ClientPrefs.save();  // Write to disk
```

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

### Initialize Bar object

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/core-classes-api.md

Constructor for creating a new health bar visualization.

```haxe
public function new(barImage:String, fillImage:String, ?x:Float, ?y:Float):Void
```

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

### Spawn Note

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/playstate-api.md

Creates and renders a note on the playfield.

```haxe
function spawnNote(note:Note):Bool
```

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

### Manage Note Spawning and Stacking

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/gameplay-systems.md

Methods for adding notes to the playfield and managing internal note structures.

```haxe
function spawnNote(note:Note):Bool
{
    // Add note to playfield
    // Configure visual properties
    // Start following strum
    return true;
}

function stackNote(note:Note):Bool
{
    // Internal note structure
    // Linked lists for sustain chains
    return true;
}
```

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

### Initialize ScriptedState

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/core-classes-api.md

Constructor for the ScriptedState class.

```haxe
public function new():Void
```

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

### Handle keyboard input

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/playstate-api.md

Methods for processing keyboard events during gameplay.

```haxe
function justPressedKey(event:KeyboardEvent):Void
```

```haxe
function justReleasedKey(event:KeyboardEvent):Void
```

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

### Define Control Mappings

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/gameplay-systems.md

Static array configuration mapping keys to note lanes.

```haxe
static var notes:Array<Array<FlxKey>> = [
    [W],           // Up arrow
    [A],           // Left arrow
    [S],           // Down arrow
    [D]            // Right arrow
];
```

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

### VideoSprite Constructor

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/core-classes-api.md

Initializes a new VideoSprite instance with a specified video path.

```APIDOC
## new VideoSprite(video: String)

### Description
Creates a new VideoSprite object to display video files in gameplay.

### Parameters
- **video** (String) - Required - Video path (without extension)
```

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

### Formatter.getChart

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/core-classes-api.md

Load and convert a song chart to ALE format.

```APIDOC
## Formatter.getChart(song:String, difficulty:String)

### Description
Load and convert song chart to ALE format.

### Parameters
- **song** (String) - Required - The song identifier.
- **difficulty** (String) - Required - The difficulty level.

### Returns
- **ALESong** - Formatted chart data
```

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

### Initialize Alphabet

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/core-classes-api.md

Constructor for creating a new Alphabet text object with optional position, text, and bold styling.

```haxe
public function new(?x:Float, ?y:Float, ?text:String, ?bold:Bool):Void
```

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

### makeLuaSprite(tag:String, ?image:String, ?x:Float, ?y:Float)

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/lua-scripting.md

Creates a basic sprite from an image file.

```APIDOC
## makeLuaSprite(tag:String, ?image:String, ?x:Float, ?y:Float)

### Description
Create a basic sprite from an image.

### Parameters
- **tag** (String) - Required - Object identifier
- **image** (String) - Optional - Image path (without extension)
- **x** (Float) - Optional - X position
- **y** (Float) - Optional - Y position
```

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

### Implement Pause and Resume Logic

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/gameplay-systems.md

Manages game state suspension and resumption, including conductor control and substate handling.

```haxe
function pause(?force:Bool = false):Void
{
    if (paused || force) {
        Conductor.pause();
        persistentUpdate = false;
        openSubState(new PauseSubState());
    }
}

function resume():Void
{
    if (paused) {
        Conductor.resume();
        persistentUpdate = true;
    }
}
```

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

### spawnNote(note:Note)

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/playstate-api.md

Creates and renders a note on the playfield.

```APIDOC
## spawnNote(note:Note)

### Description
Create and render a note on the playfield.

### Parameters
- **note** (Note) - Required - Note object to spawn

### Returns
- **Bool** - true if successfully spawned
```

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

### new(id:String, type:CharacterType)

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/core-classes-api.md

Constructor to initialize a new character instance.

```APIDOC
## Constructor

### Description
Initializes a new character with a specific identifier and role.

### Signature
`public function new(id:String, type:CharacterType):Void`

### Parameters
- **id** (String) - Character identifier (e.g., 'bf', 'dad')
- **type** (CharacterType) - PLAYER, OPPONENT, or EXTRA
```

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

### Initialize Conductor

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/core-classes-api.md

Initializes the Conductor with default timing settings. This is typically handled automatically during engine startup.

```haxe
Conductor.init();
```

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

### Stage Management

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/playstate-api.md

Methods for switching between different stage layers.

```haxe
function changeStage(id:String):Void
```

```haxe
playState.changeStage('alt'); // Switch to alternate stage
```

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

### Check Directory Existence

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/core-classes-api.md

Verifies if a specific path points to an existing directory.

```haxe
if (Paths.isDirectory('assets/images')) {
    // ...
}
```

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

### Implement custom gameplay behavior

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/playstate-api.md

Lua script hooks for responding to beat, step, and event triggers within the PlayState.

```lua
-- Lua script for PlayState
function beatHit(curBeat)
    -- Do something every beat
    if curBeat % 4 == 0 then
        -- Every 4 beats
        playState:moveCamera(playState.opponent)
    end
end

function eventHit(event)
    if event.id == 'setSpeed' then
        playState.speed = event.values[1]
    end
end

function stepHit(curStep)
    -- Slowly increase health
    playState.health = playState.health + 0.01
end
```

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

### Implement Botplay Input Logic

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/gameplay-systems.md

Checks for notes within the current time window to trigger automatic hits when botplay is enabled.

```haxe
if (botplay) {
    for (note in notes) {
        if (note.time <= Conductor.time && note.time > lastHitTime) {
            // Auto-hit the note
            playState.hitNote(note, 0, true);
        }
    }
}
```

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

### Define HMM dependencies in hmm.json

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/configuration.md

Lists the required Haxe libraries for the project build process.

```json
{
  "dependencies": [
    "haxeflixel",
    "flixel-ui",
    "hxluajit",
    "rulescript"
  ]
}
```

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

### Implement a PlayState script in Lua

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/lua-scripting.md

Handles beat-based zoom changes, custom event processing, and step-based debug logging.

```lua
-- scripts/states/play-state.lua
function beatHit(curBeat)
    -- Change zoom every 4 beats
    if curBeat % 4 == 0 then
        setZoom(1.1, 0.3, 'linear')
    end
end

function eventHit(event)
    if event.id == 'changeSpeed' then
        local speed = event.values[1]
        setProperty('playState', 'speed', speed)
    elseif event.id == 'changeCharacter' then
        local position = event.values[1]
        local id = event.values[2]
        setCharacter(position, id)
    end
end

function stepHit(curStep)
    -- Debug current position
    if curStep % 16 == 0 then
        debugPrint("Step: " .. curStep, 'trace')
    end
end
```

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

### Define Runtime Configuration in Haxe

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/configuration.md

Defines static meta and data objects for engine configuration and rhythm settings.

```haxe
public static var meta = {
    engineVersion: '0.1.0',
    developerMode: false,
    debugPrint: false,
    debugLineSize: 13,
    maxDebugLines: 50,
    // ... more properties
};

public static var data = {
    bpm: 100,
    stepsPerBeat: 4,
    beatsPerSection: 4,
    // ... more properties
};
```

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

### Initialize Strum Receptor

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/gameplay-systems.md

Constructor definition for the Strum class.

```haxe
public function new(?x:Float = 0, ?y:Float = 0):Void
```

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

### getDebugInfo():Table

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/lua-scripting.md

Retrieves debug information regarding the current game state.

```APIDOC
## getDebugInfo():Table

### Description
Get debug information about game state.

### Returns
- **Table** - Debug info containing current state details.
```

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

### Modify Gameplay State

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/playstate-api.md

Adjusting botplay and scroll speed settings.

```haxe
playState.botplay = true;
playState.speed = 1.5; // 150% speed
```

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

### Define Per-Song Conductor Settings

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/configuration.md

JSON configuration for overriding default audio timing and stage parameters.

```json
{
  "bpm": 140,
  "stepsPerBeat": 4,
  "beatsPerSection": 4,
  "speed": 1.0,
  "stage": "stage-main"
}
```

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

### Check File Existence

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/lua-scripting.md

Verifies if a file exists at the specified path.

```lua
if fileExists('data/songs/bopeebo/chart.json') then
    print("Chart exists")
end
```

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

### makeGraphic(tag:String, width:Float, height:Float, ?color:Int)

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/lua-scripting.md

Creates a colored rectangle sprite.

```APIDOC
## makeGraphic(tag:String, width:Float, height:Float, ?color:Int)

### Description
Create a colored rectangle sprite.

### Parameters
- **tag** (String) - Object identifier
- **width** (Float) - Width in pixels
- **height** (Float) - Height in pixels
- **color** (Int) - Optional - Color value (hex AARRGGBB)

### Example
```lua
makeGraphic('rect', 100, 100, 0xFF0000)
```
```

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

### Initialize Splash Effect

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/gameplay-systems.md

Constructor definition for the Splash effect class.

```haxe
public function new(strum:Strum, note:Note):Void
```

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

### playAnim(tag:String, name:String, ?forced:Bool, ?reversed:Bool, ?startFrame:Int)

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/lua-scripting.md

Plays an animation on a sprite.

```APIDOC
## playAnim(tag:String, name:String, ?forced:Bool, ?reversed:Bool, ?startFrame:Int)

### Description
Play an animation on a sprite.

### Parameters
- **tag** (String) - Object identifier
- **name** (String) - Animation name
- **forced** (Bool) - Optional - Force restart even if already playing
- **reversed** (Bool) - Optional - Play animation backwards
- **startFrame** (Int) - Optional - Frame to start from

### Example
```lua
playAnim('char', 'idle', true)
playAnim('char', 'jump', false, true)
```
```

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

### Retrieve Asset Path

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/core-classes-api.md

Resolves the full file path for a given asset and file type.

```haxe
var imagePath = Paths.getPath('characters/bf', IMAGE);
var audioPath = Paths.getPath('songs/bopeebo', AUDIO);
```

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

### Define Lua script structure

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/lua-scripting.md

Template for implementing standard lifecycle and musical callbacks in Lua scripts.

```lua
-- Called when the script initializes
function new(...)
    print("Script initialized")
end

-- Musical callbacks (for MusicBeatState)
function stepHit(curStep) end
function beatHit(curBeat) end
function sectionHit(curSection) end

function safeStepHit(safeStep) end
function safeBeatHit(safeBeat) end
function safeSectionHit(safeSection) end

-- PlayState specific
function eventHit(event) end
function update(elapsed) end
```

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

### Alphabet Constructor

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/core-classes-api.md

Initializes a new Alphabet text object.

```APIDOC
## new Alphabet(?x: Float, ?y: Float, ?text: String, ?bold: Bool)

### Description
Creates a new Alphabet object for letter-by-letter text rendering.

### Parameters
- **x** (Float) - Optional (Default: 0) - X position
- **y** (Float) - Optional (Default: 0) - Y position
- **text** (String) - Optional (Default: '') - Initial text
- **bold** (Bool) - Optional (Default: false) - Use bold font
```

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

### addAnimationByPrefix(tag:String, name:String, prefix:String, ?framerate:Int, ?loop:Bool)

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/lua-scripting.md

Adds an animation from a prefix (for atlases).

```APIDOC
## addAnimationByPrefix(tag:String, name:String, prefix:String, ?framerate:Int, ?loop:Bool)

### Description
Add animation from prefix (for atlases).

### Parameters
- **tag** (String) - Object identifier
- **name** (String) - Animation name
- **prefix** (String) - Frame name prefix
- **framerate** (Int) - Optional - Frames per second
- **loop** (Bool) - Optional - Whether animation loops

### Example
```lua
addAnimationByPrefix('char', 'idle', 'character_idle', 24, true)
```
```

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

### Calculate Note Spawn Timing

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/gameplay-systems.md

Determines the exact time a note should appear based on speed and crochet values.

```haxe
var spawnTime = noteTime - (strumLine.speed * 2000 / crochet);
```

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

### Configure Hot-Reloading in Haxe

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/configuration.md

Define directories to monitor and enable automatic reloading for script files.

```haxe
// Monitor directories for changes
HotReloading.watch('scripts/states/');
HotReloading.watch('scripts/stages/');
HotReloading.watch('data/');

// Auto-reload when files change
HotReloading.autoReload = true;
```

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

### Create a Character in Haxe

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/INDEX.md

Instantiates a character object and adds it to the current PlayState.

```haxe
var bf = new Character('bf', PLAYER);
playState.addCharacter(bf);
```

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

### Define Path Configuration Structure

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/configuration.md

Defines the typedef for path configuration, including file types and caching settings.

```haxe
typedef PathConfig = {
    path:String,
    types:Array<FileType>,
    cache:PathConfigCache
}
```

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

### Define JsonStageSpritesConfig structure

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/types.md

Configures background objects, including asset directory and default properties.

```haxe
typedef JsonStageSpritesConfig = {
    directory:String,
    sprites:Array<JsonStageObject>,
    properties:Dynamic
}
```

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

### Retrieve debug information in Lua

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/lua-scripting.md

Fetches a table containing current game state information.

```lua
local info = getDebugInfo()
print(info.currentState)  -- Current state class name
```

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

### Search Complex File

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/core-classes-api.md

Searches for a file path, accounting for both mods and base assets.

```haxe
var path = CoolUtil.searchComplexFile('songs/bopeebo');
```

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

### makeLuaFunkinSprite(tag:String, data:JsonSprite, ?imageDirectory:String)

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/lua-scripting.md

Creates a sprite using a JSON configuration object.

```APIDOC
## makeLuaFunkinSprite(tag:String, data:JsonSprite, ?imageDirectory:String)

### Description
Create a sprite from JSON config.

### Parameters
- **tag** (String) - Required - Object identifier
- **data** (Table) - Required - JsonSprite config
- **imageDirectory** (String) - Optional - Asset directory
```

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

### doGlobalTimer(time:Float, callback:String, ?loops:Int)

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/lua-scripting.md

Creates a global timer that executes a specified Lua function after a delay, with optional repetition.

```APIDOC
## doGlobalTimer(time:Float, callback:String, ?loops:Int)

### Description
Creates a timer that calls a Lua function after the specified duration.

### Parameters
- **time** (Float) - Required - Duration in seconds
- **callback** (String) - Required - Function name to call
- **loops** (Int) - Optional - Number of repetitions
```

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

### Paths.audio()

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/core-classes-api.md

Retrieves the full path for an audio asset.

```APIDOC
## Paths.audio(path:String)

### Description
Get audio asset path.

### Parameters
- **path** (String) - Required - Audio path

### Returns
- **String** - Full path
```

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

### readFile(path:String):String

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/lua-scripting.md

Reads the entire content of a file as a string.

```APIDOC
## readFile(path:String):String

### Description
Reads the entire content of a file as a string.

### Parameters
- **path** (String) - Required - The file path to read.

### Returns
- **String** - The contents of the file.
```

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

### justPressedKey(event:KeyboardEvent):Void

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/playstate-api.md

Handles keyboard note input events.

```APIDOC
## justPressedKey(event:KeyboardEvent):Void

### Description
Handle keyboard note input.

### Signature
`function justPressedKey(event:KeyboardEvent):Void`
```

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

### Load Sprite from JSON

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/core-classes-api.md

Populates sprite data from a JSON configuration object with an optional asset prefix.

```haxe
sprite.fromJson(characterConfig, 'characters/bf/');
```

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

### listDirectory(path:String):Table

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/lua-scripting.md

Retrieves a list of all files within a specified directory.

```APIDOC
## listDirectory(path:String):Table

### Description
Retrieves a list of all files within a specified directory.

### Parameters
- **path** (String) - Required - The directory path.

### Returns
- **Table** - An array of file names.
```

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

### icon.bop(?amount:Float)

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/gameplay-systems.md

Animates the icon bobbing on beat.

```APIDOC
## bop(?amount:Float)

### Description
Triggers a bobbing animation for the icon.

### Parameters
- **amount** (Float) - Optional - Scale change amount (Default: 0.05)
```

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

### Check Animation Playability

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/core-classes-api.md

Verify if an animation exists and is valid to play before triggering it.

```haxe
if (bopper.shouldPlayAnim('idle')) {
    bopper.playAnim('idle');
}
```

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

### Define JsonHudCombo structure

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/types.md

Configures the combo display, containing settings for both rating and number animations.

```haxe
typedef JsonHudCombo = {
    > JsonBase,
    properties:Dynamic,
    rating:JsonHudComboRating,
    number:JsonHudComboNumber
}
```

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

### pause(?force:Bool)

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/playstate-api.md

Pauses the current song and freezes gameplay mechanics.

```APIDOC
## pause(?force:Bool)

### Description
Pause the song and freeze gameplay.

### Parameters
- **force** (Bool) - Optional - Default: false - Force pause even if already paused
```

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

### initCharacters()

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/playstate-api.md

Creates all characters from stage and strumline configuration.

```APIDOC
## initCharacters()

### Description
Create all characters from stage and strumline configuration.

### Signature
`function initCharacters():Void`
```

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

### Music Event Callbacks

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/playstate-api.md

Override these methods to handle song state changes such as play, pause, and completion.

```haxe
override function musicPlay():Void
```

```haxe
override function musicPause():Void
```

```haxe
override function musicResume():Void
```

```haxe
override function musicStop():Void
```

```haxe
override function musicComplete():Void
```

```haxe
override function musicResync():Void
```

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

### Apply Shaders in Scripts

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/configuration.md

Lua functions for loading and removing custom shaders from game objects.

```lua
-- Load custom shader
local shader = makeShader('my-shader')
setShader('mySprite', shader)

-- Remove shader
setShader('mySprite', nil)
```

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

### saveFile(path:String, content:String, ?overwrite:Bool)

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/lua-scripting.md

Writes a string to a file, with an optional overwrite flag.

```APIDOC
## saveFile(path:String, content:String, ?overwrite:Bool)

### Description
Writes a string to a file.

### Parameters
- **path** (String) - Required - The file path.
- **content** (String) - Required - The content to write.
- **overwrite** (Bool) - Optional - Whether to overwrite an existing file.
```

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

### stackEventList(eventList:ALEEventList)

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/playstate-api.md

Queues a list of events at a specific time to be processed by the game engine.

```APIDOC
## stackEventList(eventList:ALEEventList)

### Description
Queue events at a specific time to be processed.

### Parameters
- **eventList** (ALEEventList) - Required - Events with timestamp
```

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

### Calculate Score and Handle Notes

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/gameplay-systems.md

Logic for processing note hits and misses within the PlayState.

```haxe
// Hit a note
var rating = playState.judgeNote(timeDistance);
playState.score += rating.score;
playState.combo += 1;

// Miss a note
playState.missNote(note);
playState.combo = 0;
playState.misses += 1;
playState.health -= missHealth;
```

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

### CoolUtil.setProperties

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/core-classes-api.md

Set multiple object properties at once.

```APIDOC
## CoolUtil.setProperties(obj:Dynamic, properties:Dynamic)

### Description
Set multiple object properties at once.

### Parameters
- **obj** (Dynamic) - Required - Object to modify.
- **properties** (Dynamic) - Required - Property map {key: value}.
```

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

### Save File Content

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/lua-scripting.md

Writes a string to a file, with an optional overwrite flag.

```lua
saveFile('data/custom.json', jsonString, true)
```

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

### Playback Control Methods

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/playstate-api.md

Methods for controlling song playback, including pausing, resuming, restarting, and exiting the state.

```haxe
function pause(?force:Bool = false):Void
```

```haxe
function resume():Void
```

```haxe
function restart():Void
```

```haxe
function endSong():Void
```

```haxe
function exit():Void
```

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

### Define JsonKeyBind structure

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/types.md

Represents keyboard binding configuration with a display name, control variable, and default key codes.

```haxe
typedef JsonKeyBind = {
    name:String,
    variable:String,
    initial:Array<String>
}
```

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

### Add Character

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/playstate-api.md

Adds a character instance to the stage.

```haxe
function addCharacter(char:Character):Void
```

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

### Define a Script Callback in Lua

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/INDEX.md

Uses the beatHit callback to modify game properties based on musical beats.

```lua
-- scripts/states/play-state.lua
function beatHit(curBeat)
    if curBeat % 4 == 0 then
        setProperty('playState', 'speed', 1.1)
    end
end
```

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

### Manage HUD Elements

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/playstate-api.md

Methods for initializing and updating HUD components like scores, combos, and character icons.

```haxe
function initHud():Void
```

```haxe
function initCombo():Void
```

```haxe
function displayCombo(rating:JsonHudRating):Void
```

```haxe
function updateScoreText():Void
```

```haxe
function updateHealth():Void
```

```haxe
function initIcons():Void
```

```haxe
function addIcon(icon:Icon):Void
```

```haxe
function changeIcon(icon:Icon, id:String):Void
```

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

### Handle Keyboard Input in PlayState

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/gameplay-systems.md

Processes key press and release events to trigger note hits or sustain releases.

```haxe
function justPressedKey(event:KeyboardEvent):Void
{
    // Map key code to note lane
    var noteData = Controls.keyToNoteData(event.keyCode);
    
    if (noteData != null) {
        // Check for hittsble notes
        var note = getNoteAtTime(noteData);
        if (note != null) {
            hitNote(note, timeDistance, true);
        }
    }
}

function justReleasedKey(event:KeyboardEvent):Void
{
    // Handle sustain note release
    var noteData = Controls.keyToNoteData(event.keyCode);
    // Release sustain notes
}
```

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

### Configure Health UI in JSON

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/gameplay-systems.md

Specifies the image assets used for the health bar background and filling.

```json
{
  "bar": "healthbar",           // Background bar image
  "barFilling": "healthbar-hd"  // Fill overlay image
}
```

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

### Music Beat Callbacks

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/playstate-api.md

Override these methods to execute custom logic on specific musical beats or sections.

```haxe
override function stepHit(curStep:Int):Void
```

```haxe
override function beatHit(curBeat:Int):Void
```

```haxe
override function sectionHit(curSection:Int):Void
```

```haxe
override function safeStepHit(safeStep:Int):Void
```

```haxe
override function safeBeatHit(safeBeat:Int):Void
```

```haxe
override function safeSectionHit(safeSection:Int):Void
```

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

### List Directory Contents

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/lua-scripting.md

Retrieves an array of file names present in the specified directory.

```lua
local files = listDirectory('data/custom/')
for _, file in ipairs(files) do
    print(file)
end
```

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

### Define Asset Cache Configuration

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/configuration.md

Defines the structure for asset caching settings including memory limits and clearing behavior.

```haxe
typedef CacheConfig = {
    clearUnused:Bool,
    clearOnState:Bool,
    maxMemory:Int
}
```

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

### stackNote(note:Note)

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/playstate-api.md

Adds a note to the playfield.

```APIDOC
## stackNote(note:Note)

### Description
Add a note to the playfield. Returns whether note was added.

### Parameters
- **note** (Note) - Required - Note object to add

### Returns
- **Bool** - true if successfully added
```

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

### Gameplay Event Hooks

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/playstate-api.md

Lua script hooks for customizing gameplay behavior during beats, steps, and events.

```APIDOC
## Gameplay Event Hooks

### beatHit(curBeat)
Triggered every beat. 

### stepHit(curStep)
Triggered every step.

### eventHit(event)
Triggered when a custom event occurs.
```

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

### Icon(id:String)

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/gameplay-systems.md

Constructor for the Icon class, used to initialize a character health bar indicator.

```APIDOC
## new(id:String)

### Description
Creates a new instance of the Icon class for a specific character.

### Parameters
- **id** (String) - Required - Character ID
```

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

### Define StrumLine Configuration

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/gameplay-systems.md

Typedef defining the structure for StrumLine configuration, including visual and functional properties.

```haxe
typedef JsonStrumLineConfig = {
    id:String,
    note:String,
    sustain:String,
    end:String,
    splashSkin:String,
    type:CharacterType,
    direction:Float,
    position:Point,
    noteType:String,
    ?downScroll:Bool,
    ?properties:Dynamic
}
```

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

### followStrum():Void

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/gameplay-systems.md

Updates the note's position and visual properties to align with its receptor.

```APIDOC
## Method: followStrum()

### Description
Updates note position and properties to follow its receptor. This method is intended to be called every frame during gameplay.

### Behavior
- Calculates visual position based on time distance and speed.
- Copies properties from parent strum if configured.
- Applies clipping to sustain notes as they are hit.
```

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

### Define OptionType enumeration

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/types.md

Defines the data types for configuration options.

```haxe
enum abstract OptionType(String) {
    var BOOL = 'bool';
    var STATE = 'state';
    var SUBSTATE = 'state';
    var STRING = 'string';
    var INT = 'int';
    var FLOAT = 'float';
}
```

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

### Create a Global Timer

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/lua-scripting.md

Initiates a timer that triggers a specified Lua function after a set duration, with optional repetition.

```lua
doGlobalTimer(2.0, 'myCallback', 3)  -- 2 second timer, repeat 3 times
```

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

### getFileDirectory(path:String):String

Source: https://github.com/ale-psych-crew/ale-psych/blob/main/_autodocs/lua-scripting.md

Extracts the directory path from a full file path.

```APIDOC
## getFileDirectory(path:String):String

### Description
Extracts the directory path from a full file path.

### Parameters
- **path** (String) - Required - The file path.

### Returns
- **String** - The directory path.
```