Contributing

Welcome to the Contributing Guide! You can contribute to the Funkin' repository by opening issues or pull requests.

This guide will cover best practices for each type of contribution.

Part 1: Etiquette

Be respectful to one another. We're here to help each other out!
Keep your titles clear and concise. Do not type the whole description into the title.
Do not spam by creating unnecessary issues and pull requests.
Use common sense!

Part 2: Issues

Issues serve many purposes, from reporting bugs to suggesting new features. This section provides guidelines to follow when opening an issue.

Requirements

Make sure you're playing:

the latest version of the game (currently v0.5.3)
without any mods
on Newgrounds or downloaded from itch.io

Rejected Features

If you want to suggest a feature, make sure it hasn't already been rejected. Here's a list of commonly suggested features and the reasons why they won't be added:

Feature	Reason
Combo Break + Accuracy Displays	#2681 (comment)
Toggleable Ghost Tapping	#2564 (comment)
Perfectly Centered Strumlines	same as above^
MultiKey, 9k, More than 4 keys, etc.	#4243 (comment)
Losing Icons for DD and Parents	#3048 (comment)
Playable GF / Speaker BF / Speaker Pico	#2953 (comment)
Fresh (Chill Mix) as Title Screen Music	#4282 (comment)
Adjusted Difficulty Ratings	#2781 (comment)
Difficulty Ratings above 20	#3075 (comment)
Ability to Reset a Song's Score	#3916 (comment)
Quick Restart Keybind (not R)	#3268 (comment)
Countdown after Unpausing Song	#2721 (comment)
4:3 Aspect Ratio for Week 6	#3840 (comment)
"Philly Glow" Effect from Psych Engine	#3788 (comment)
Importing Charts from Psych Engine (and other mod content)	#2586 (comment)
Backwards Compatibility for Modding	#3949 (comment)
Lua Support	#2643 (comment)

Issue Types

Choose the issue template that best suits your needs! Here's what each template is designed for:

Bug Report (view list)

For minor bugs and general issues with the game. Choose this one if none of the others fit your needs.

Crash Report (view list)

For crashes and freezes like the Null Object Reference problem from v0.3.0.

Charting Issue (view list)

For misplaced notes, wonky camera movements, broken song events, and everything related to the game's charts.

Enhancement (view list)

For suggestions to add new features or improve existing ones. We'd love to hear your ideas!

Compiling Help (only after reading the Troubleshooting Guide)

For issues with compiling the game. Legacy versions (before v0.3.0) are not supported.

Tip

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

Before You Submit...

Complete the Issue Checklist at the top of your template!

Important

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

Be sure to use the search bar on the Issues page to check that your issue hasn't already been reported by someone else. Duplicate issues make it harder to keep track of important issues with the game.

Also only report one issue or enhancement at a time! If you have multiple bug reports or suggestions, split them up into separate submissions so they can be checked off one by one.

Once you're sure your issue is unique and specific, feel free to submit it.

Important

DO NOT CLOSE YOUR ISSUE FOR ANY REASON! Your issue will be taken care of by a moderator!

Thank you for opening issues!

Part 3: Pull Requests

Community members are welcome to contribute their changes by opening pull requests. This section covers guidelines for opening and managing pull requests (PRs).

Choosing a base branch

When creating a branch in your fork, base your branch on either the main or develop branch depending on the types of changes you want to make.

Caution

Avoid using your fork's default branch (main in this case) for your PR. This is considered an anti-pattern by GitHub themselves! Instead, make a separate branch for your additions (ex. docs/fix-typo or minor-bugfix).

Choose the main branch if you modify:

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

Choose the develop branch if you modify:

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

Tip

When in doubt, base your branch on the develop branch.

Choosing the right base branch helps keep your commit history clean and avoid merge conflicts. Once you’re satisfied with the changes you’ve made, open a PR and base it on the same branch you previously chose.

Merge conflicts and rebasing

Some game updates introduce significant breaking changes that may create merge conflicts in your PR. To resolve them, you will need to update or rebase your PR.

Most merge conflicts are small and will only require you to modify a few files to resolve them. However, some changes are so big that your commit history will look like a mess! In this case, you will have to perform a rebase. This process reapplies your changes on top of the updated branch and cleanly resolves the merge conflicts.

Tip

If your commit history becomes too long, you can use rebase to squash your PR's commits into a single commit.

Code PRs

Important

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

Code-based PRs make changes such as fixing bugs or implementing new features in the game.

This involves modifying one or several of the repository’s .hx files, found within the source/ folder.

Codestyle

Before submitting your PR, check that your code follows the Style Guide. This keeps your code consistent with the rest of the codebase!

Code comments

Code comments help others understand your changes, so the way you write them is important! Here are some guidelines for writing comments in your code:

Leave comments only when you believe a piece of code warrants explanation. If a piece of code is self-explanatory, it does not need a comment.
Ensure that your comments provide meaningful insight into the function or purpose of the code.
Write your comments in a clear and concise manner.
Only sign your comments with your name when your changes are complex and may require further explanation.

Example code comments

DO NOT:

Below are examples of what you SHOULD NOT do when writing 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 - [GitHub 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 to the target time
  {
    FlxG.sound.music.time = targetTimeMs;
  }

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

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

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

// End the song when the music is complete.
FlxG.sound.music.onComplete = function() {
  endSong(skipEndingTransition);
};
// A negative instrumental offset means the song skips the first few milliseconds of the track.
// This just gets added into the startTimestamp behavior so we don't need to do anything extra.
FlxG.sound.music.play(true, Math.max(0, startTimestamp - Conductor.instance.combinedOffset));
FlxG.sound.music.pitch = playbackRate;

// Prevent the volume from being wrong.
FlxG.sound.music.volume = 1.0;
// IF fadetween is not null we cancel it
if (FlxG.sound.music.fadeTween != null) FlxG.sound.music.fadeTween.cancel();

// Play the vocals
trace('Playing vocals...');
// Add the vocals
add(vocals);
// Play the vocals for real this time lol
vocals.play();
// Set the vocals volume
vocals.volume = 1.0;
// Set the vocals pitch
vocals.pitch = playbackRate;
// Set the vocals time to the music time
vocals.time = FlxG.sound.music.time;
// trace('${FlxG.sound.music.time}');
// trace('${vocals.time}');
// functionThatWasntHereBeforeThisPRorSomethingIdKLOL();
/* testsprite = new FlxSprite(0, 0);
testsprite.loadGraphic(Paths.image('test'));
testsprite.screenCenter();
add(testsprite); */

// Me too [GitHub username] I hate this function it gave me pain and suffering - Girlfriend
resyncVocals();

#if FEATURE_DEBUG_FUNCTIONS
// PAGEUP: who knows what this does
// SHIFT+PAGEUP: There will be dire consequences.
if (FlxG.keys.justPressed.PAGEUP) changeSection(FlxG.keys.pressed.SHIFT ? 20 : 2);
// PAGEUP: who knows what this does
// SHIFT+PAGEUP: There will be dire consequences.
if (FlxG.keys.justPressed.PAGEDOWN) changeSection(FlxG.keys.pressed.SHIFT ? -20 : -2);
#end

DO:

Below are examples on what you SHOULD do when writing 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();
}

FlxG.sound.music.onComplete = function() {
  endSong(skipEndingTransition);
};
// A negative instrumental offset means the song skips the first few milliseconds of the track.
// This just gets added into the startTimestamp behavior so we don't need to do anything extra.
FlxG.sound.music.play(true, Math.max(0, startTimestamp - Conductor.instance.combinedOffset));
FlxG.sound.music.pitch = playbackRate;

// Prevent the volume from being wrong.
FlxG.sound.music.volume = 1.0;
if (FlxG.sound.music.fadeTween != null) FlxG.sound.music.fadeTween.cancel();

trace('Playing vocals...');
add(vocals);
vocals.play();
vocals.volume = 1.0;
vocals.pitch = playbackRate;
vocals.time = FlxG.sound.music.time;
resyncVocals();

#if FEATURE_DEBUG_FUNCTIONS
// PAGEUP: Skip forward two sections.
// SHIFT+PAGEUP: Skip forward twenty sections.
if (FlxG.keys.justPressed.PAGEUP) changeSection(FlxG.keys.pressed.SHIFT ? 20 : 2);
// PAGEDOWN: Skip backward two section. Doesn't replace notes.
// SHIFT+PAGEDOWN: Skip backward twenty sections.
if (FlxG.keys.justPressed.PAGEDOWN) changeSection(FlxG.keys.pressed.SHIFT ? -20 : -2);
#end

Documentation PRs

Documentation-based PRs make changes such as fixing typos or adding new information in documentation files.

This involves modifying one or several of the repository’s .md files, found throughout the repository.

Make sure your changes are easy to understand and formatted consistently to maximize clarity and readability.

Caution

DO NOT TOUCH THE LICENSE.md FILE, EVEN TO MAKE SMALL CHANGES!

Example Documentation PR

DO NOT:

// The original documentation
- `F2`: ***OVERLAY***: Enables the Flixel debug overlay, which has partial support for scripting.
- `F3`: ***SCREENSHOT***: Takes a screenshot of the game and saves it to the local `screenshots` directory. Works outside of debug builds too!
- `F4`: ***EJECT***: Forcibly switch state to the Main Menu (with no extra transition). Useful if you're stuck in a level and you need to get out!
- `F5`: ***HOT RELOAD***: Forcibly reload the game's scripts and data files, then restart the current state. If any files in the `assets` folder have been modified, the game should process the changes for you! NOTE: Known bug, this does not reset song charts or song scripts, but it should reset everything else (such as stage layout data and character animation data).
- `CTRL-SHIFT-L`: ***FORCE CRASH***: Immediately crash the game with a detailed crash log and a stack trace.

// The new PR additions
- `ctrl alt shift e`: No idea what this does
- `alt-f4`: closes the game

DO:

// The original documentation
- `F2`: ***OVERLAY***: Enables the Flixel debug overlay, which has partial support for scripting.
- `F3`: ***SCREENSHOT***: Takes a screenshot of the game and saves it to the local `screenshots` directory. Works outside of debug builds too!
- `F4`: ***EJECT***: Forcibly switch state to the Main Menu (with no extra transition). Useful if you're stuck in a level and you need to get out!
- `F5`: ***HOT RELOAD***: Forcibly reload the game's scripts and data files, then restart the current state. If any files in the `assets` folder have been modified, the game should process the changes for you! NOTE: Known bug, this does not reset song charts or song scripts, but it should reset everything else (such as stage layout data and character animation data).
- `CTRL-SHIFT-L`: ***FORCE CRASH***: Immediately crash the game with a detailed crash log and a stack trace.

// The new PR additions
- `CTRL-ALT-SHIFT-E`: ***DUMP SAVE DATA***: Prompts the user to save their save data as a JSON file, so its contents can be viewed. Only available on debug builds.
- `ALT-F4`: ***CLOSE GAME***: Closes the game forcibly on Windows.

GitHub PRs

GitHub-related PRs make changes such as tweaking Issue Templates or updating the repository’s workflows.

This involves modifying one or several of the repository’s .yml files, or any other file in the .github folder.

Please test these changes on your fork’s main branch to avoid breaking anything in this repository (e.g. GitHub Actions, issue templates, etc.)!

funkin.assets PRs

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

If you only modify files in the assets folder, open a PR in the funkin.assets repository instead of the main repository.

If you simultaneously modify files from both repositories, then open two separate PRs and explain the connection in your PR descriptions.

Be sure to choose main as the base branch for funkin.assets PRs, as no develop branch exists for that repository.

Charting PRs

Charting PRs make changes such as adding/removing notes or adjusting the placement of song events.

This involves modifying one or several of the funkin.assets repository's .json chart files, found in the preload/data/songs/ directory.

These PRs should only be opened in the funkin.assets repository.

Caution

No Major Recharts! Any PR that makes major chart modifications will be rejected. Keep your PRs to small tweaks and fixes.

Here are some guidelines for opening a Charting PR:

Explain the issue. Which song, variation, difficulty, and section/timestamp is the problem in? Help us understand with screenshots and videos.
Show your changes. How does the chart look with your changes? Provide screenshots and videos here as well.
Minimize the diff. If your changes are very small (e.g. a few notes), do not re-export the chart using the Chart Editor. Instead, manually edit the .json chart files to help GitHub display your changes cleanly.

If your PR is accepted, you will be credited as a GitHub contributor (but not as a charter in the Pause Menu).

Closing

Thank you for reading the Contributing Guide.

We look forward to seeing your contributions to the game!

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Files

CONTRIBUTING.md

CONTRIBUTING.md

Contributing

Table of Contents

Part 1: Etiquette

Part 2: Issues

Requirements

Rejected Features

Issue Types

Bug Report (view list)

Crash Report (view list)

Charting Issue (view list)

Enhancement (view list)

Compiling Help (only after reading the Troubleshooting Guide)

Before You Submit...

Part 3: Pull Requests

Choosing a base branch

Merge conflicts and rebasing

Code PRs

Codestyle

Code comments

Example code comments

DO NOT:

DO:

Documentation PRs

Example Documentation PR

DO NOT:

DO:

GitHub PRs

funkin.assets PRs

Charting PRs

Closing

Files

CONTRIBUTING.md

Latest commit

History

CONTRIBUTING.md

File metadata and controls

Contributing

Table of Contents

Part 1: Etiquette

Part 2: Issues

Requirements

Rejected Features

Issue Types

Bug Report (view list)

Crash Report (view list)

Charting Issue (view list)

Enhancement (view list)

Compiling Help (only after reading the Troubleshooting Guide)

Before You Submit...

Part 3: Pull Requests

Choosing a base branch

Merge conflicts and rebasing

Code PRs

Codestyle

Code comments

Example code comments

DO NOT:

DO:

Documentation PRs

Example Documentation PR

DO NOT:

DO:

GitHub PRs

funkin.assets PRs

Charting PRs

Closing