DOCSEARCHbyAlgolia
Submit Docs

Codename Engine Documentation

repository·main·Indexed 19 days ago

https://github.com/codenamecrew/codenameengine

A cross-platform Friday Night Funkin' engine designed for simplified modding through advanced softcoding and extensibility. It serves as the official successor to the Yoshi Engine and utilizes Hscript Improved for scripting. Documentation covers compilation for Windows, Linux, and MacOS using Haxe 4.3.7, language translation guides, addon installation, and a comprehensive shader compatibility and porting guide for OpenFL/Flixel.

Tokens
4.7K
Snippets
12
Records
26
Agent score
66%

What's inside Codename Engine

  1. Codename Engine Usage and Licensing Guidelines

    main

    The project follows specific rules regarding how its code can be used.

    Permitted Uses

    • Download and play the engine with mods/modpacks.
    • Mod and fork the engine (provided it is not for illicit purposes).
    • Contribute via Pull Requests or Issues.
    • Create a sub engine using Codename Engine as a TEMPLATE, provided you include CREDITS (e.g., listing GitHub contributors in a credits menu and specifying the sub engine origin in the README).
    • Release executable mods that use Codename Engine as source (with proper attribution).
    • Release Codename Engine modpacks.

    Prohibited Uses

    • Creating a side/new engine (or a mod that does not use Codename Engine) using Codename Engine's code.
    • Stealing code for non-Codename Engine related projects without proper credit.
    • Releasing the entirety of Codename Engine on other platforms (standalone mods are permitted).

    For specific questions not covered here, contact the developers on their Discord server.

  4. Understand the folder structure for scripting events

    main

    Events in the scripting system are organized into folders based on their primary functional relationship or the core concept they represent, rather than strictly by the class that triggers them.

    When looking for an event, do not assume it is located in a folder named after its trigger class. Instead, look for folders related to the event's subject matter. For example:

    • gameplay folder: Contains events triggered during active gameplay, such as GameOverEvent, even if they are called by the PlayState class.
    • note folder: Contains events related to notes, such as NoteHitEvent, even if they are triggered by both PlayState and StrumLine (the Input Notes class).

    Use this conceptual grouping to navigate the source/funkin/backend/scripting/events/ directory structure.

  6. Compile Codename Engine on Windows

    main

    To turn the source code into a playable build on Windows, follow these steps:

    1. Install Haxe version 4.3.7.
    2. Download and install git-scm (use default installation options).
    3. Run setup-windows.bat via CMD or by double-clicking it to install required libraries.
    4. Once libraries are installed, compile and launch the game using: haxelib run lime test windows

    Tips:

    • To make the lime command global (allowing you to run lime test windows directly), run haxelib run lime setup.
    • For easier development, you can use the custom build script ./cne-windows.bat test (or ./building/cne-windows.bat test if running from the project root), which uses the source assets folder instead of the export folder.
    haxelib run lime test windows
# Or if lime is set up globally:
lime test windows

  7. Compile Codename Engine on Linux

    main

    To turn the source code into a playable build on Linux, follow these steps:

    1. Install Haxe version 4.3.7.
    2. Install libvlc. (Note: On some Arch-based distributions, installing vlc-plugins-all may be necessary if libvlc alone fails).
    3. Install g++.
    4. Download and install git-scm.
    5. Run setup-unix.sh via the terminal to install required libraries.
    6. Once libraries are installed, compile and launch the game using: haxelib run lime test linux

    Tips:

    • To make the lime command global, run haxelib run lime setup.
    • For easier development, use ./cne-unix.sh test (or ./building/cne-unix.sh test from the project root) to use source assets instead of exported ones.
    haxelib run lime test linux
# Or if lime is set up globally:
lime test linux

  9. Avoid common shader compatibility mistakes

    main

    To ensure shaders work across all devices (including AMD GPUs and macOS), follow these compatibility rules:

    • Float Literals: Always use 0.0 instead of 0. or .0. Many GPUs (like AMD) do not support half-floats.
    • Control Flow: Use if statements instead of switch cases, as switch is unsupported on macOS and other platforms.
    • Vector Initialization: Do not use integers to initialize vectors (e.g., use vec2(1.0, 1.0) instead of vec2(1, 1)). Use floats for all expected float inputs, such as mod(1.0, 2.0).
    • Unsupported Types: Avoid using ivec2,3,4, bvec2,3,4, uvec2,3,4, and uint as they are unsupported on certain platforms.
    • Variable Naming:
      • Do not start variable names with gl_ (e.g., float gl_Number may break the shader).
      • Do not name variables input or sample, as this causes failures on AMD GPUs.
    • Operators: Do not use the % operator; use the mod() function instead.
    • Arrays: Avoid using arrays whenever possible.
    • Uniforms: You cannot apply defaults to uniforms in the shader code. Set defaults in your shader constructor or immediately after initialization in your code.
    • Suffixes: Avoid using the <number>u suffix (e.g., 8u).

  11. Compile Codename Engine on MacOS

    main

    To turn the source code into a playable build on MacOS, follow these steps:

    1. Install Haxe version 4.3.7.
    2. Install Xcode to enable C++ application building.
    3. Download and install git-scm.
    4. Run setup-unix.sh via the terminal to install required libraries.
    5. Once libraries are installed, compile and launch the game using: haxelib run lime test mac

    Tips:

    • To make the lime command global, run haxelib run lime setup.
    • For easier development, use ./cne-unix.sh test (or ./building/cne-unix.sh test from the project root) to use source assets instead of exported ones.
    haxelib run lime test mac
# Or if lime is set up globally:
lime test mac

  12. Install addons using ZIP files

    main

    Codename Engine supports installing addons via ZIP files, but they must follow a specific directory hierarchy. The data folder and other assets must be located at the root of the ZIP archive.

    Correct Structure:

    addon.zip/
    📁data
    📁images
    ...

    Incorrect Structure (will not work): Do not wrap the addon contents inside a subfolder within the ZIP. For example, the following structure is invalid:

    addon.zip/
    📁my addon/
        📁data
        📁images
        ...