Contributing to Friday Night Funkin'

Welcome to the Contributing Guide! You can contribute to the Funkin’ repository by opening issues or pull requests. This guide covers best practices for each type of contribution.

Etiquette

Be respectful to one another. We’re here to help each other out!
Keep titles clear and concise. Don’t put the whole description in the title.
Don’t spam by creating unnecessary issues and pull requests.
Use common sense!

Opening Issues

Issues serve many purposes, from reporting bugs to suggesting new features.

Before You Submit

Make sure you’re playing:

The latest version of the game (currently v0.8.3)
Without any mods
On Newgrounds or downloaded from itch.io

Use the search bar on the Issues page to check that your issue hasn’t already been reported. Duplicate issues make it harder to track problems.

Issue Types

Choose the issue template that best suits your needs:

Bug Report

For minor bugs and general issues with the game. Choose this if none of the other templates fit.View open bug reports →

Crash Report

For crashes and freezes that make the game unplayable.View open crash reports →

Charting Issue

For misplaced notes, wonky camera movements, broken song events, and everything related to the game’s charts.View open charting issues →

Enhancement

For suggestions to add new features or improve existing ones. We’d love to hear your ideas!View open enhancement requests →

Compiling Help

For issues with compiling the game. Only after reading the Troubleshooting Guide.Legacy versions (before v0.3.0) are not supported.

If none of the above templates suit your inquiry (e.g., Questions or Coding Help), please open a discussion.

Rejected Features

If you want to suggest a feature, make sure it hasn’t already been rejected. Here are commonly suggested features that won’t be added:

Feature	Reason
Combo Break + Accuracy Displays	See reasoning
Toggleable Ghost Tapping	See reasoning
Perfectly Centered Strumlines	Same as above
MultiKey, 9k, More than 4 keys	See reasoning
Flashy Combo Milestones	See reasoning
Losing Icons for DD and Parents	See reasoning
Quick Restart Keybind (not R)	See reasoning
Countdown after Unpausing	See reasoning
Importing Charts from Psych Engine	See reasoning
Backwards Compatibility for Modding	See reasoning
Lua Support	See reasoning

Issue Checklist

If you do not complete each step of the Issue Checklist in your template, your issue may be closed.

Be sure to:

Search for duplicates before submitting
Report only one issue per submission
Complete all required fields in the template

Submitting Pull Requests

Community members are welcome to contribute code changes by opening pull requests.

This guide does not cover compilation. If you have trouble compiling, refer to the Compilation Guide.

Choosing a Base Branch

Avoid using your fork’s default branch (main) for your PR. This is an anti-pattern by GitHub!Instead, make a separate branch (e.g., docs/fix-typo or bugfix/player-health).

Choose the develop branch if you modify:

Game code (.hx files)
Any other type of file

Choose the main branch if you modify:

Documentation (.md files)
GitHub files (.yml files or anything in .github/)

When in doubt, base your branch on develop.

Maintaining Your Pull Request

Our maintenance policy:

If we require changes, we’ll label your PR status: needs revision
You have 90 days to implement requested changes
After 90 days, your PR will be closed as status: stale
You can request to reopen closed PRs if you address the issues

Merge Conflicts and Rebasing

Some game updates may create merge conflicts in your PR. You’ll need to resolve them by updating or rebasing.

When to rebase

If your commit history becomes messy due to large conflicts, perform a rebase.Rebasing reapplies your changes on top of the updated branch and cleanly resolves conflicts.You can also use rebase to squash multiple commits into one.

Code Pull Requests

Code-based PRs make changes like fixing bugs or implementing features. This involves modifying .hx files in the source/ folder.

Follow the Style Guide

Before submitting, check that your code follows the Style Guide.

Code Comments Best Practices

DO ✓
DON'T ✗

Good code comments:

/**
 * Jumps forward or backward a number of sections in the song.
 * Accounts for BPM changes, does not prevent death from skipped notes.
 * @param sections The number of sections to jump, negative to go backwards.
 */
function changeSection(sections:Int):Void
{
  var targetTimeSteps:Float = Conductor.instance.currentStepTime 
    + (Conductor.instance.stepsPerMeasure * sections);
  var targetTimeMs:Float = Conductor.instance.getStepTimeInMs(targetTimeSteps);

  // Don't go back in time to before the song started.
  targetTimeMs = Math.max(0, targetTimeMs);

  if (FlxG.sound.music != null)
  {
    FlxG.sound.music.time = targetTimeMs;
  }

  handleSkippedNotes();
  SongEventRegistry.handleSkippedEvents(songEvents, Conductor.instance.songPosition);
  Conductor.instance.update(FlxG.sound?.music?.time ?? 0.0);
  resyncVocals();
}

What makes this good:

Clear function documentation
Only comments things that need explanation
Concise and meaningful

Bad code comments:

/**
 * jumps around the song
 * works with bpm changes but skipped notes still hurt
 * @param sections how many sections to jump, negative = backwards
 */
function changeSection(sections:Int):Void
{
  // Pause the music, as you probably guessed
  // FlxG.sound.music.pause();

  // Set the target time in steps, I don't really get how this works though lol - [Username]
  var targetTimeSteps:Float = Conductor.instance.currentStepTime 
    + (Conductor.instance.stepsPerMeasure * sections);
  var targetTimeMs:Float = Conductor.instance.getStepTimeInMs(targetTimeSteps);

  // Don't go back in time to before the song started, that would probably 
  // break a lot of things and cause a bunch of problems!
  targetTimeMs = Math.max(0, targetTimeMs);

  if (FlxG.sound.music != null) // If the music is not null, set the time
  {
    FlxG.sound.music.time = targetTimeMs;
  }

  // Handle skipped notes and events and all that jazz
  handleSkippedNotes();
  SongEventRegistry.handleSkippedEvents(songEvents, Conductor.instance.songPosition);

  Conductor.instance.update(FlxG.sound?.music?.time ?? 0.0);

  // I hate this function - [Username]
  resyncVocals();
}

What makes this bad:

Commented-out code left in
Explaining obvious things
Personal comments that don’t help understanding
Lowercase function documentation
Overly verbose explanations

Code Comment Guidelines

Only comment when code needs explanation
Ensure comments provide meaningful insight
Write clearly and concisely
Only sign comments when changes are complex and may need follow-up
Never leave commented-out code — remove it or keep it elsewhere

Documentation Pull Requests

Documentation PRs make changes like fixing typos or adding information in .md files. Make sure your changes are:

Easy to understand
Formatted consistently
Clear and readable

DO NOT TOUCH THE LICENSE.md FILE, even for small changes!

GitHub Pull Requests

GitHub-related PRs modify .yml files or anything in the .github/ folder (like issue templates or workflows).

Test these changes on your fork’s main branch to avoid breaking the repository!

Funkin.assets Pull Requests

The assets submodule has its own repository: funkin.assets.

If you only modify files in assets/, open a PR in funkin.assets
If you modify files in both repos, open two separate PRs and link them
Base your PR on the develop branch

Charting Pull Requests

Charting PRs modify *-metadata.json files in preload/data/songs/.

We do not accept changes to chart .json files themselves.If you find a chart error, open an issue in the main Funkin repo. The Funkin’ Crew will review and make adjustments.

Next Steps

Style Guide

Learn code formatting conventions

Compilation Guide

Set up your development environment

Troubleshooting

Fix common compilation issues

GitHub Repository

View the source code

Thank you for reading the Contributing Guide. We look forward to seeing your contributions!

Getting Started

Development

Modding

Game Systems

Tools

Contributing to Friday Night Funkin'

Etiquette

Opening Issues

Before You Submit

Issue Types

Rejected Features

Issue Checklist

Submitting Pull Requests

Choosing a Base Branch

Maintaining Your Pull Request

Merge Conflicts and Rebasing

Code Pull Requests

Follow the Style Guide

Code Comments Best Practices

Code Comment Guidelines

Documentation Pull Requests

GitHub Pull Requests

Funkin.assets Pull Requests

Charting Pull Requests

Next Steps

Style Guide

Compilation Guide

Troubleshooting

GitHub Repository

Build docs developers (and LLMs) love

Getting Started

Development

Modding

Game Systems

Tools

​Etiquette

​Opening Issues

​Before You Submit

​Issue Types

​Rejected Features

​Issue Checklist

​Submitting Pull Requests

​Choosing a Base Branch

​Maintaining Your Pull Request

​Merge Conflicts and Rebasing

​Code Pull Requests

​Follow the Style Guide

​Code Comments Best Practices

​Code Comment Guidelines

​Documentation Pull Requests

​GitHub Pull Requests

​Funkin.assets Pull Requests

​Charting Pull Requests

​Next Steps

Style Guide

Compilation Guide

Troubleshooting

GitHub Repository

Build docs developers (and LLMs) love

Etiquette

Opening Issues

Before You Submit

Issue Types

Rejected Features

Issue Checklist

Submitting Pull Requests

Choosing a Base Branch

Maintaining Your Pull Request

Merge Conflicts and Rebasing

Code Pull Requests

Follow the Style Guide

Code Comments Best Practices

Code Comment Guidelines

Documentation Pull Requests

GitHub Pull Requests

Funkin.assets Pull Requests

Charting Pull Requests

Next Steps