From 4b883d43390f444bb62f291bb1df90677cc4f13a Mon Sep 17 00:00:00 2001 From: Hundrec Date: Sat, 5 Apr 2025 22:23:56 -0600 Subject: [PATCH] Restore Contributing Guide to latest version Merge conflicts yay Co-Authored-By: Abnormal <86753001+AbnormalPoof@users.noreply.github.com> --- docs/CONTRIBUTING.md | 228 ++++++++++++++++++++++++++++++++----------- 1 file changed, 170 insertions(+), 58 deletions(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index d9eea297b..0f1985fab 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -39,6 +39,8 @@ This guide will cover best practices for each type of contribution. * [funkin.assets PRs](https://github.com/FunkinCrew/Funkin/blob/main/docs/CONTRIBUTING.md#funkinassets-prs) + * [Charting PRs](https://github.com/FunkinCrew/Funkin/blob/main/docs/CONTRIBUTING.md#charting-prs) + [Closing](https://github.com/FunkinCrew/Funkin/blob/main/docs/CONTRIBUTING.md#closing) @@ -58,7 +60,7 @@ This section provides guidelines to follow when [opening an issue](https://githu ## Requirements Make sure you're playing: -- the latest version of the game (currently v0.5.3) +- the latest version of the game (currently v0.6.2) - without any mods - on [Newgrounds](https://www.newgrounds.com/portal/view/770371) or downloaded from [itch.io](https://ninja-muffin24.itch.io/funkin) @@ -122,6 +124,9 @@ Also only report one issue or enhancement at a time! If you have multiple bug re 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 @@ -133,6 +138,7 @@ When creating a branch in your fork, base your branch on either the `main` or `d > [!CAUTION] > Avoid using your fork's default branch (`main` in this case) for your PR. This is considered an [anti-pattern](https://jmeridth.com/posts/do-not-issue-pull-requests-from-your-master-branch/) 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) @@ -165,81 +171,169 @@ This process reapplies your changes on top of the updated branch and cleanly res > This guide does not cover compiling. If you have trouble compiling the game, refer to the [Compilation Guide](https://github.com/FunkinCrew/Funkin/blob/main/docs/COMPILING.md). 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](https://github.com/FunkinCrew/Funkin/blob/main/docs/style-guide.md). +Before submitting your PR, check that your code follows the [Style Guide](https://github.com/FunkinCrew/Funkin/blob/main/docs/style-guide.md). 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. +- 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 Comments +### Example code comments #### DO NOT: +Below are examples of what you SHOULD NOT do when writing code comments. ```haxe - /** - * 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 +/** + * 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 { - // 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 whole 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(); + 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(); +} +``` + +```haxe +// 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(); +``` + +```haxe +#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. ```haxe - /** - * 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 +/** + * 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) { - 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.time = targetTimeMs; } + + handleSkippedNotes(); + SongEventRegistry.handleSkippedEvents(songEvents, Conductor.instance.songPosition); + + Conductor.instance.update(FlxG.sound?.music?.time ?? 0.0); + + resyncVocals(); +} +``` + +```haxe +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(); +``` + +```haxe +#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 @@ -297,7 +391,25 @@ If you simultaneously modify files from both repositories, then open two separat 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! +We look forward to seeing your contributions to the game! \ No newline at end of file