Skip to main content

​
What is Modding?

Friday Night Funkin’ features a powerful modding system that allows you to customize nearly every aspect of the game. From replacing assets to creating entirely new gameplay mechanics with scripts, the modding framework gives you extensive control over your game experience.

Powered by Polymod

FNF uses Polymod, an atomic modding framework for Haxe games that provides asset replacement, merging, and scripting capabilities.

​
Polymod Architecture

The modding system is built on Polymod, a robust framework that handles:
  • Asset Loading: Automatic detection and loading of mod files from the mods folder
  • Asset Replacement: Override any game asset by placing a replacement in your mod
  • Asset Merging: Append or merge data into existing text files
  • Script Execution: Run custom HScript code to extend game functionality
  • Mod Management: Load multiple mods with priority ordering

​
Core Components

The modding system consists of several key components:

PolymodHandler

Main interface for loading and managing mods. Located in funkin/modding/PolymodHandler.hx

IScriptedClass

Interfaces defining callbacks for scripted classes. Located in funkin/modding/IScriptedClass.hx

Module System

Global scripts that receive events from any game state. Located in funkin/modding/module/

ScriptEvent System

Event dispatching system for scripts. Located in funkin/modding/events/

​
What You Can Mod

​
Assets

Replace or modify any game asset:
  • Images - Character sprites, backgrounds, UI elements
  • Audio - Music, sound effects, voice lines
  • Data Files - Charts, character data, stage configurations
  • Text Files - Dialogue, intro text, credits

​
Gameplay

Modify game behavior with scripts:
  • Custom Characters - Create new characters with unique behaviors
  • Custom Stages - Design new stages with interactive elements
  • Note Types - Add new note mechanics
  • Song Events - Create custom chart events
  • UI Modifications - Change menus, HUD elements, transitions

​
Scripts

Write custom code using HScript:
  • Modules - Global scripts that run across all game states
  • Scripted Classes - Extend base classes like FlxSprite, FlxState
  • Event Handlers - React to gameplay events (notes, beats, state changes)
  • Custom Logic - Implement entirely new mechanics

​
API Version

Friday Night Funkin’ uses semantic versioning for mod compatibility: 
/**
 * The API version for the current version of the game.
 */
public static var API_VERSION(get, never):String;

static function get_API_VERSION():String
{
  return Constants.VERSION;
}

/**
 * The Semantic Versioning rule
 * Indicates which mods are compatible with this version of the game.
 */
public static final API_VERSION_RULE:String = ">=0.8.0 <0.9.0";
Mods must specify a compatible api_version in their _polymod_meta.json file. The game only loads mods that match the version rule.

​
Mod Detection

Mods are loaded from the mods folder: 
FridayNightFunkin.exe
mods/
  └── yourmod/
      ├── _polymod_meta.json
      └── ...
The game automatically detects mods on startup by scanning the mods folder for valid _polymod_meta.json files.

​
Security & Sandboxing

For security, the modding system restricts access to sensitive functionality:
  • File System: Limited to sandboxed operations via FileUtilSandboxed
  • Newgrounds API: Read-only access, no score/medal manipulation
  • System Commands: No access to Sys, cpp.Lib, native processes
  • Reflection: Restricted via ReflectUtil to prevent blacklist bypass
  • Save Data: No direct score manipulation
Scripts cannot execute malicious code or access system resources outside the game’s sandbox.

​
Next Steps

Installing Mods

Learn how to install mods on your platform

Creating Mods

Start building your first mod

Scripting Guide

Write custom scripts with HScript

Polymod Deep Dive

Advanced Polymod features and techniques

Build docs developers (and LLMs) love

Get started for freeTalk to us