Quick Start Guide

Prerequisites

Before compiling Friday Night Funkin’, you need to install the required tools:

Haxe

Download from haxe.org
Required for compiling the game

Git

Download from git-scm.com
Required for cloning the repository

Do NOT download using the “Download ZIP” button on GitHub! This will cause errors with asset loading. Always use Git to clone the repository.

Installation Steps

Navigate to Your Workspace

Open a command prompt/terminal and navigate to where you want the source code:

cd C:\Users\YOURNAME\Documents

On macOS/Linux, use paths like cd ~/Documents or cd ~/Developer

Clone the Repository

Clone the official Friday Night Funkin’ repository:

git clone https://github.com/FunkinCrew/funkin.git

Then enter the directory:

cd funkin

Download Game Assets

The game assets are in a separate submodule. Download them with:

git submodule update --init --recursive

Important Legal Notice: By downloading these assets, you are accessing proprietary content protected by copyright and trademark laws. See the assets LICENSE for terms.

Install Haxe Package Manager

Install hmm (Haxe Module Manager) for managing dependencies:

haxelib --global install hmm
haxelib --global run hmm setup

Having trouble with Lime?

If you encounter issues installing Lime, try using Funkin’s patched libraries:

haxelib --global git haxelib https://github.com/FunkinCrew/haxelib.git
haxelib --global git hmm https://github.com/FunkinCrew/hmm.git

Install All Dependencies

Install all required Haxe libraries defined in hmm.json:

hmm install

This installs 30+ dependencies including:

flixel: Game engine
polymod: Modding framework
hxvlc: Video playback (desktop)
newgrounds: Newgrounds API
And many more…

Set Up Lime

Configure the Lime framework:

haxelib run lime setup

Follow the prompts to complete setup.

Platform-Specific Setup

Complete the setup for your target platform:

Windows
macOS
Linux
HTML5

Download Visual Studio Build ToolsWhen prompted, select “Individual Components” and install:

✅ MSVC v143 VS 2022 C++ x64/x86 build tools
✅ Windows 10/11 SDK

You don’t need the full Visual Studio IDE—just the Build Tools are sufficient.

Install Xcode Command Line Tools:

xcode-select --install

Then run Lime’s macOS setup:

lime setup mac

See Lime’s macOS documentation for detailed instructions.

Install required packages. For Ubuntu/Debian:

sudo apt install libvlc-dev libvlccore-dev libvlccore9

Then run Lime’s Linux setup:

lime setup linux

For other distributions, refer to hxvlc’s documentation for equivalent packages.

Build Native Libraries (Optional)

For native desktop builds, rebuild the platform-specific libraries:

# Release build
lime rebuild windows

# Debug build
lime rebuild windows -debug

Replace windows with mac or linux for other platforms.

This step is optional but recommended for first-time setup to ensure all C++ libraries are properly compiled.

Compile and Run

Build and launch the game:

lime test windows

Replace windows with your target platform:

windows - Windows desktop
mac - macOS desktop
linux - Linux desktop
html5 - Web browser

The first build will take several minutes. Subsequent builds are much faster thanks to incremental compilation.

Build Configurations

Debug vs Release Builds

Debug Build
Release Build

Debug builds include development features:

lime test windows -debug

Enabled Features:

In-game debug functions (time travel with PgUp/PgDn)
VSCode debug server for breakpoints
Asset redirection from source folder
No compiler optimizations
Verbose logging

Use Cases:

Active development
Testing and debugging
Content creation

Release builds are optimized for distribution:

lime test windows

Enabled Features:

Compiler optimizations
Stripped debug symbols
Embedded assets
Better performance

Use Cases:

Final builds for players
Performance testing
Distribution

Common Build Flags

Customize your build with feature flags:

# Enable specific features
lime test windows -DGITHUB_BUILD          # Enable debug features in release
lime test windows -DFEATURE_CHART_EDITOR  # Enable chart editor
lime test windows -DFEATURE_STAGE_EDITOR  # Enable stage editor
lime test windows -DFEATURE_GHOST_TAPPING # Enable ghost tapping

# Disable features
lime test windows -DNO_FEATURE_VIDEO_PLAYBACK   # Disable videos
lime test windows -DNO_FEATURE_DISCORD_RPC      # Disable Discord
lime test windows -DNO_FEATURE_POLYMOD_MODS     # Disable mods

A complete list of build flags is documented in project.hxp. The flags control compilation of optional features to reduce build size and dependencies.

Asset Redirection

For rapid iteration during development:

lime test windows -debug -DREDIRECT_ASSETS_FOLDER

This makes the game load assets directly from the assets/ folder instead of the export folder, allowing you to test changes without recompiling.

Builds with asset redirection enabled won’t work if distributed to other users—they need the full workspace structure.

Build Output Locations

Compiled builds are placed in the export/ directory:

funkin/
└── export/
    ├── debug/
    │   ├── windows/
    │   │   └── bin/
    │   │       └── Funkin.exe
    │   ├── mac/
    │   ├── linux/
    │   └── html5/
    └── release/
        └── windows/
            └── bin/
                └── Funkin.exe

Verify Your Build

Once the game launches, verify it’s working correctly:

Check Version

The current version should display as v0.8.3 on the title screen.

Test Main Menu

Navigate through the main menu options:

Story Mode
Freeplay
Options

Test a Song

Play a song in Freeplay to verify:

Audio playback works
Notes appear correctly
Input is responsive
Graphics render properly

If you encounter issues, check the Troubleshooting Guide in the repository.

Quick Reference

Essential Commands

Command	Purpose
`hmm install`	Install/update all dependencies
`lime test <platform>`	Compile and run the game
`lime build <platform>`	Compile without running
`lime clean <platform>`	Clean build artifacts
`lime rebuild <platform>`	Rebuild native libraries

File Locations

Path	Contents
`source/`	Haxe source code
`assets/`	Game assets (submodule)
`project.hxp`	Build configuration
`hmm.json`	Dependency versions
`export/`	Compiled builds

Next Steps

Learn to Play

Master the controls and gameplay mechanics

Start Modding

Create custom content with the modding framework

Contribute

Submit improvements to the main repository

Join Community

Connect with other developers and modders

Development Workflow

Once you have the game running, here’s a typical development workflow:

Make Changes

Edit source code in source/ or assets in assets/

Hot Reload (Optional)

Press F5 in-game to reload scripts and data without recompiling (debug builds only)

Recompile

Run lime test windows -debug to rebuild and launch

Test

Verify your changes work as expected

Commit

Use Git to commit your changes

The hot reload feature (F5) works for most assets and scripts but does not reload song charts or compiled code changes—those require a full recompile.

Getting Started

Development

Modding

Game Systems

Tools

Prerequisites

Haxe

Git

Installation Steps

Build Configurations

Debug vs Release Builds

Common Build Flags

Asset Redirection

Build Output Locations

Verify Your Build

Quick Reference

Essential Commands

File Locations

Next Steps

Learn to Play

Start Modding

Contribute

Join Community

Development Workflow

Build docs developers (and LLMs) love

Getting Started

Development

Modding

Game Systems

Tools

​Prerequisites

Haxe

Git

​Installation Steps

​Build Configurations

​Debug vs Release Builds

​Common Build Flags

​Asset Redirection

​Build Output Locations

​Verify Your Build

​Quick Reference

​Essential Commands

​File Locations

​Next Steps

Learn to Play

Start Modding

Contribute

Join Community

​Development Workflow

Build docs developers (and LLMs) love

Prerequisites

Installation Steps

Build Configurations

Debug vs Release Builds

Common Build Flags

Asset Redirection

Build Output Locations

Verify Your Build

Quick Reference

Essential Commands

File Locations

Next Steps

Development Workflow