Cool Engine

Engine

Templates & Starters

Tools

A collection of mods made by the community using Cool Engine. Want yours listed here? See the submission info below.

Cool Engine is a full-featured Friday Night Funkin' fork aimed at modders and developers. It extends the base game with a robust asset cache, multi-layer scripting, mod compatibility for Psych Engine / Codename / V-Slice formats, in-game editors, 3D scene support, and a native C++ extension layer for Windows/macOS/Linux.

The engine follows a strict 11-step initialization order in Main.hx to ensure each subsystem has its dependencies ready before it starts.

• 1
  DPI-awareness + dark mode — InitAPI calls SetProcessDPIAware() and enables dark titlebar. Must run before any window is created.
• 2
  GC tuning — Garbage collector parameters configured before any assets are loaded.
• 3
  Stage config — OpenFL stage scale mode and alignment set up.
• 4
  AudioConfig.load() — Must run before createGame() so audio settings are ready before OpenAL initializes.
• 5
  CrashHandler, DebugConsole — Crash reporting and dev console registered.
• 6
  createGame() — FlxGame instance created, FlxG becomes available.
• 7
  AudioConfig.applyToFlixel() — Settings pushed to FlxG audio after Flixel is ready.
• 8
  WindowManager.init() — Window resize subscription and scale mode set.
• 9
  Save data, keybinds, note skins — All FlxG-dependent systems (save file, key bindings, NoteSkinSystem) initialized.
• 10
  UI overlays — DataInfoUI, SoundTray, and ScreenshotPlugin added to the stage.
• 11
  SystemInfo.init() — GPU/system information collected; requires context3D which is only available after the first rendered frame.

FunkinCache manages all texture, sound, and font assets using a three-layer system that balances memory efficiency with smooth state transitions.

Performance Improvements (v2)

• Batch eviction — clearSecondLayer() collects all keys then does a single-pass removal, avoiding Map re-hashing on each individual delete.
• Hot path optimization — getBitmapData() checks CURRENT first and short-circuits SECOND if not needed.
• O(1) counters — Bitmap/sound/font counts maintained as running totals, not computed by iterating.
• Mod fallback — Searches the active mod directory before falling back to disk.
• Eviction callbacks — Mods can register onEvict callbacks to react when their assets are destroyed.

ScriptHandler v3 manages all scripts with a layered loading system. Scripts are organized by scope layer and loaded from predictable folder paths.

Script Folder Paths

Key Script Hooks (Gameplay)

RuleScript — LuaJIT Scripting

RuleScript is the primary scripting system in Cool Engine v0.6.0B. Scripts are plain .lua files with a transparent bridge to all Haxe classes and instances — no sandboxing, no wrapper functions to memorise. Just real Lua with full OOP access.

RuleScript replaces the old handle-based system. All legacy helper functions (newObject, setProp, getProperty, etc.) remain available for backward compatibility, but you no longer need them.

Enabling RuleScript

Add these lines to your Project.xml:

Then place .lua files in any of the script folder paths shown above.

Live Globals

These objects are available in every RuleScript automatically:

OOP Access

All Haxe objects are accessed directly through Lua proxy tables. Fields are read/written with dot notation; methods are called with colon syntax (to pass self) or dot syntax.

import

Imports a Haxe class or enum and registers it as a global short name. You can use any of these syntaxes — they all do the same thing:

Imports placed at the top of the file are resolved before the interpreter runs, so the class is available everywhere — including inside other imports and module-level code.

before() / after() / replace()

Three simple verbs for hooking into any method on any object. No original parameter, no self — just the actual arguments you care about.

Legacy: overrideMethod(obj, name, function(original, self, ...)) still works for backward compat.

require()

Loads another .lua file as a reusable module. The module's global exports are returned as a table. Results are cached — the file runs only once.

Custom Classes

Use the built-in Class helper to define OOP classes in Lua. Instances are created with ClassName.new(...) and the init method is called automatically.

Inheritance

Extend an existing class by passing it as the second argument to Class:

switchState()

Transition to any engine state by name:

Legacy API (backward compat)

All old Lua wrapper functions still work. You do not need to migrate existing scripts.

Full RuleScript Example

Minimal state example

State with animated sprite & sounds

Scripted SubState

Available helpers inside StateScript

Chart events are processed by EventManager, which dispatches typed events to registered handlers. Custom event types are registered in EventRegistry and can be defined by mods.

Built-in Event Types

PlayState is the main gameplay state. It coordinates all gameplay subsystems through dedicated controller classes, keeping the core file manageable.

The note system is built for performance, using object pooling and GPU batching to handle large note counts without hitching.

• NotePool — Object pool that recycles Note instances. Avoids garbage collection spikes during dense sections.
• NoteBatcher — Groups note draw calls into batches sent to the GPU renderer in a single pass.
• NoteSkinSystem — Loads per-skin note graphics from assets/images/noteSkins/. Skins can override arrows, holds, splashes, and cover animations.
• NoteHoldCover — Animated cover that plays when a hold note starts, driven by a shader clip for seamless visual continuity.
• NoteSplash — Hit effect sprites pooled and reused on Sick hits.

Every note skin and splash can optionally include a script (.lua or .hx) that runs alongside the skin, giving you full access to gameplay hooks, the RGB color shader, tween functions, and the OOP bridge — all scoped to that skin or splash.

Folder structure

Drop a skin.lua (or skin.hx) alongside your skin.json. The filename can also be overridden with the "script" field in the JSON.

Note skin script — skin.lua

The engine pre-injects these variables before calling onCreate:

Note skin script — callbacks

Splash script — splash.lua

Variables injected before onCreate: same RGB helpers as above, plus splashName instead of skinName.

Hold splash (cover) script — inside splash.lua

Hold covers use the same splash script file. They fire a separate callback.

HScript equivalent

Everything above works identically in skin.hx / splash.hx. You can also use the full OOP bridge:

JSON fields — skin.json

These fields are added to the root of your skin.json:

colorAuto — automatic RGB coloring

Inspired by Psych Engine and Nightmare Engine's RGB note coloring. Uses a GLSL matrix shader that remaps the R, G, B channels of your note texture to any color per direction — so a single grayscale/neutral atlas can look fully colored in-game.

Minimal — standard FNF colors

With reduced intensity (70%)

Custom palette (4 directions)

colorAuto also works on splashes & hold covers

Add the same fields to your splash.json. The shader is applied automatically on every setup() call for both NoteSplash and NoteHoldCover.

RGB shader tween API (Lua)

These functions are available in any Lua script (song, stage, skin, splash) — not just skin scripts.

Default direction color presets

All available callbacks

Mods live in the mods/ directory. Each mod is a folder with a mod.json descriptor. Only one mod can be active at a time. Use ModManager.setActiveMod(id) to switch.

mod.json Structure

Mod Folder Structure

Engine Overrides

Mods can override engine behavior via mod_overrides.json or a ModEngineOverride class. Overrideable systems include: HUD class, note spawning system, character loading, stage loading.

Addons are lightweight plugins that run on top of any active mod. Unlike mods, multiple addons can be active simultaneously. They are loaded after mods so they can read the active folder.

addon.json Hooks

ChartLoader auto-detects chart format and routes to the appropriate parser. No manual format specification required.

Subtitle Support

The SubtitleManager + SRTParser provides full SRT subtitle rendering for videos, with configurable styles (font, size, position, background).

CoreAudio wraps OpenAL for low-latency audio. MusicManager handles background music transitions. Character-specific vocals are loaded as streaming audio.

• AudioConfig — Loaded before createGame(). Configures sample rate, period size, and latency before OpenAL initializes.
• VolumePlugin — Manages master, music, and SFX volume levels with smooth tweening.
• VSyncAPI — Native VSync control. Prevents audio drift on high-refresh-rate displays.
• FrameLimiterAPI — Improves OS timer precision (Windows: timeBeginPeriod(1)) for accurate high-FPS pacing.

• GPURenderer — Manages sprite batching pools, submits batched draw calls to reduce GPU overhead during gameplay.
• RenderOptimizer — Tracks render budget per frame, applies adaptive quality (lower effect resolution, skip optional passes).
• OptimizationManager — Coordinates GPU and CPU optimization levels based on real-time performance metrics.
• FunkinCamera — Extended FlxCamera with built-in shader filter support and fixed BitmapData for zero-allocation frame capture.
• Flx3DScene — Lightweight 3D rendering layer built on Stage3D/Context3D. Supports OBJ models, .mtl materials, lighting, and custom GLSL shaders.

All editors are accessible from EditorHubState, opened via a debug menu shortcut during gameplay (when Developer Mode is enabled in mod settings).

HScript files are placed in the appropriate folder (e.g. mods/{mod}/songs/{song}/scripts/myscript.hx). The engine injects all of these variables automatically — you don't need to import anything.

Flixel Core

Gameplay Globals

Gameplay — game.*

Score Object — score.*

Camera Object — camera.*

HUD Object — hud.*

Characters — chars.*

States — states.*

Persistent Data — data.*

Signal Bus — signal.*

Events — events.*

Shaders

Math Utilities — math.*

Array Helpers — arr.*

ModChart — ModChartManager.*

Defining Custom Classes (HScript)

Lua scripts work the same as in Psych Engine but with a much larger API. They are detected automatically by file extension and loaded from the same folder paths as HScript files.

Object Registry

Sprites

Text

Camera

Tweens

Timers

Gameplay

Characters (Lua)

Notes (Lua)

ModChart (Lua)

Audio (Lua)

Events (Lua)

Input (Lua)

Script Communication (Lua)

Utils (Lua)

You can build entirely new screens (states) using HScript without writing Haxe. Place a .hx file in mods/{mod}/states/{StateName}/ and navigate to it with states.goto("StateName").

Minimal state example

State with animated sprite & sounds

Scripted SubState

Available helpers inside StateScript

Place a script at mods/{mod}/characters/scripts/{charName}/script.hx. The engine injects character (the Character instance) and game (PlayState) automatically.

All CharacterScript callbacks

Cutscenes can be defined as JSON or built dynamically in Lua/HScript. Place them in mods/{mod}/videos/ or trigger them from a song script.

SpriteCutscene JSON Format

Triggering cutscenes from scripts

Lua cutscene builder API

Dialogue is defined in JSON and loaded by DialogueBoxImproved. Place files in assets/data/dialogue/ or mods/{mod}/data/dialogue/.

Custom note types let you define notes that trigger special behavior on hit, miss, or hold. Register them from a global script that loads early.

Define these functions in your script and the engine will call them automatically at the right moment.

Lifecycle — all states

PlayState only

Cancellable callbacks

HScript — cancel with return true

Lua — cancelling

Cool Engine has two levels of control over engine behavior: callbacks run alongside the engine, and hooks let you run before, after, or instead of any method on any object.

before() / after() / replace()

Works in both HScript and RuleScript (Lua). No original parameter — just the real arguments. The object you hook can be anything: game, bf, dad, a sprite, a class instance.

Lua examples

HScript examples

Example — fully custom scoring

StateScript overrides (HScript only)

Inside a StateScript you can also use overrideFunction to replace a named callback registered by the engine on that specific state. This is separate from the object-level before/after/replace system above.

Create full screens and menus entirely from HScript, without touching any Haxe code.

Folder structure

Navigating to the state

Example — full selection menu

ScriptableSubState — popups

Creating objects

Display list

Tweens & timers

Camera

Sound

Centering & screen info

Navigation

Shared data

Broadcast

Get another script

Execution priority

Hot-reload (developer mode)

states API — navigation from scripts

scripts API — internal broadcast

Cool Engine has a unified shader system built around ShaderManager and FunkinRuntimeShader. Shaders live in assets/shaders/ or mods/{mod}/shaders/ and are picked up automatically on startup.

Shader file types

Using shaders from scripts

Script shaders (.lua / .hx)

Put a .lua or .hx file in the shaders folder instead of a plain .frag. The script defines the GLSL source in a frag variable and updates uniforms in onUpdate(elapsed). No separate .frag file needed.

Once defined, use it exactly like any other shader:

Script shader API

Callbacks

Direct FunkinRuntimeShader API

If you import the shader class directly you get the full uniform API:

Built-in engine shaders