Quick Start Guide

Get Friday Night Funkin’ compiled and running on your machine with this step-by-step guide for Windows, macOS, and Linux.

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

1. 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

2. Clone the Repository

   Clone the official Friday Night Funkin’ repository:

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

   Then enter the directory:

   cd funkin
   
3. 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.

4. 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
   
5. 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…
6. Set Up Lime

   Configure the Lime framework:

   haxelib run lime setup
   

   Follow the prompts to complete setup.

7. Platform-Specific Setup

   Complete the setup for your target platform:

   Windows

   Download Visual Studio Build Tools

   When 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.

   macOS

   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.

   Linux

   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.

   HTML5

   No additional setup required! HTML5 builds compile without extra dependencies.

   HTML5 builds are great for quick testing since they compile faster than native builds.

8. 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.

9. 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

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 Build

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:

1. Check Version

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

2. Test Main Menu

   Navigate through the main menu options:

   • Story Mode
   • Freeplay
   • Options
3. 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:

1. Make Changes

   Edit source code in source/ or assets in assets/

2. Hot Reload (Optional)

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

3. Recompile

   Run lime test windows -debug to rebuild and launch

4. Test

   Verify your changes work as expected

5. 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.