Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 14 additions & 12 deletions assets/content/cookbook/Advanced/2.ScriptedClasses.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,25 +24,27 @@ class BallisticSong extends Song {

There is a predefined list of classes which the game has set up to be scriptable, and will automatically load and execute when relevant. More of these will be added in the future.

- `funkin.play.song.Song` for providing unique behavior to custom songs, including playing cutscenes and other stuff. See [Scripted Songs](21-scripted-classes/21-01-scripted-songs.md).
- See also [Video Cutscenes](21-scripted-classes/21-03-video-cutscenes.md), [Ingame Cutscenes](21-scripted-classes/21-04-ingame-cutscenes.md), and [Dialogue Cutscenes](21-scripted-classes/21-05-dialogue-cutscenes.md)
- `funkin.play.character.BaseCharacter` for providing unique behavior to custom characters (such as playing custom animations in certain circumstances). See [Scripted Characters](21-scripted-classes/21-05-scripted-characters.md).
- `funkin.play.song.Song` for providing unique behavior to custom songs, including playing cutscenes and other stuff. See [Scripted Songs](3.ScriptedSongs.md).
- See also [Video Cutscenes](6.VideoCutscenes.md), [Ingame Cutscenes](21-scripted-classes/21-04-ingame-cutscenes.md), and [Dialogue Cutscenes](7.DialogueCutscenes.md)
- `funkin.play.character.BaseCharacter` for providing unique behavior to custom characters (such as playing custom animations in certain circumstances). See [Scripted Characters](4.ScriptedCharacters.md).

- Note that you need to choose the correct subclass of this class for the animation type of your character!
- `funkin.play.character.SparrowCharacter` is used for characters that have Sparrow spritesheet animations.
- `funkin.play.character.MultiSparrowCharacter` is used for characters that have several Sparrow spritesheet animations to combine into one character.
- `funkin.play.character.PackerCharacter` is used for characters that have Packer spritesheet animations.
- `funkin.play.character.AnimateAtlasCharacter` is used for characters that have Adobe Animate texture atlases.
- `funkin.play.character.BaseCharacter` has empty stubs for all the rendering and animation handlers, and is only useful for people who want to reimplement their character's animation system by hand.

- `funkin.play.character.SparrowCharacter` is used for characters that have Sparrow spritesheet animations.
- `funkin.play.character.MultiSparrowCharacter` is used for characters that have several Sparrow spritesheet animations to combine into one character.
- `funkin.play.character.PackerCharacter` is used for characters that have Packer spritesheet animations.
- `funkin.play.character.AnimateAtlasCharacter` is used for characters that have Adobe Animate texture atlases.
- `funkin.play.character.BaseCharacter` has empty stubs for all the rendering and animation handlers, and is only useful for people who want to reimplement their character's animation system by hand.
- `funkin.play.stage.Stage` for providing unique behavior to custom stages, such as creating custom moving props and defining when props animate or when sound effects play in sync with the stage. See [Scripted Stages](21-scripted-classes/24-06-scripted-stages.md).
- `funkin.ui.story.Level` for providing unique behavior to levels in Story Mode. See [Scripted Story Levels](21-scripted-classes/25-07-scripted-story-levels.md).
- `funkin.play.notes.notekind.NoteKind` for providing unique visuals and behavior to certain kinds of notes, which can then be placed in the Chart Editor. See [Custom Note Kinds](21-scripted-classes/26-00-custom-note-kinds.md).
- `funkin.play.event.SongEvent` for creating custom Song Events, which you can place in the Chart Editor and which perform game actions when they are reached. See [Custom Song Events](21-scripted-classes/28-00-custom-note-kinds.md)
- `funkin.ui.freeplay.charselect.PlayableCharacter` for providing unique behavior to custom playable characters. See [Scripted Playable Characters](21-scripted-classes/25-10-scripted-playable-characters.md)
- `funkin.ui.freeplay.charselect.PlayableCharacter` for providing unique behavior to custom playable characters. See [Scripted Playable Characters](5.ScriptedPlayableCharacters.md)
- `funkin.ui.freeplay.FreeplayStyle` for defining the sprites and colors used by the Freeplay menu when a given character is selected. See [WIP]
- `funkin.play.notes.notestyle.NoteStyle` for modifying the behavior of custom note styles. See [WIP]
- `funkin.play.cutscene.dialogue.Conversation` for providing unique behavior to custom dialogue conversations. See [Dialogue Cutscenes](21-scripted-classes/21-05-dialogue-cutscenes.md)
- `funkin.play.cutscene.dialogue.DialogueBox` for providing unique behavior to custom dialogue boxes used in conversations. See [Dialogue Cutscenes](21-scripted-classes/21-05-dialogue-cutscenes.md)
- `funkin.play.cutscene.dialogue.Speaker` for providing unique behavior to custom speakers used in conversations. See [Dialogue Cutscenes](21-scripted-classes/21-05-dialogue-cutscenes.md)
- `funkin.play.cutscene.dialogue.Conversation` for providing unique behavior to custom dialogue conversations. See [Dialogue Cutscenes](7.DialogueCutscenes.md)
- `funkin.play.cutscene.dialogue.DialogueBox` for providing unique behavior to custom dialogue boxes used in conversations. See [Dialogue Cutscenes](7.DialogueCutscenes.md)
- `funkin.play.cutscene.dialogue.Speaker` for providing unique behavior to custom speakers used in conversations. See [Dialogue Cutscenes](7.DialogueCutscenes.md)
- `funkin.ui.freeplay.Album` for defining custom behavior for Freeplay Albums. See [WIP]

There is also `funkin.modding.module.Module` for custom scripted Modules, which are scripts which receive events everywhere, rather than only in a specific context. See [Scripted Modules](30-scripted-modules/30-00-scripted-modules.md) for more information on how these work.
Expand Down
36 changes: 32 additions & 4 deletions assets/content/cookbook/Intermediate/1.CustomPlayableCharacters.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,27 +10,36 @@ This chapter goes over adding new playable characters to the game, ensuring that

In order to make a fleshed out custom character that can be used from Character Select in Friday Night Funkin', you need a large number of textures, animations, and audio tracks:

- A [custom character](../03-custom-characters/03-00-custom-characters.md)
- A [custom character](../Introduction/3.CustomCharacters.md).

- This requires a set of singing animations for the character.
- At least one custom song that uses that character; this can be either [a new song](../02-custom-songs-and-custom-levels/02-02-adding-the-custom-song.md) or a [variation added to an existing song](../02-custom-songs-and-custom-levels/02-05-adding-variations-to-existing-songs.md).
- At least one custom song that uses that character; this can be either [a new song](../Introduction/2.CustomSongs.md#adding-the-custom-song) or a [variation added to an existing song](../Introduction/2.CustomSongs.md#adding-variations-to-existing-songs).

- This requires an instrumental and split vocal tracks.
- A pixel icon asset to use for that character's icon in the Character Select grid.

- This supports either a static image or a Sparrow spritesheet (which includes the animation to play when the character is selected).
- A namecard asset to use for that character's name above them in the Character Select menu.

- The pixellation effect is done in code so this just needs to be a single static image.
- Animations for the character to use in the Character Select menu.

- This is currently hard-coded to use an Adobe Animate texture atlas and cannot use a Sparrow spritesheet.
- The character needs animations for unlock, idle, slide in, slide out, select, and deselect.
- Assets to use for the character's Girlfriend character to the left of them in the Character Select menu.

- This is currently hard-coded to use an Adobe Animate texture atlas and cannot use a Sparrow spritesheet.
- The character needs animations for unlock, idle, slide in, slide out, select, and deselect.
- Assets for the character to use on the Freeplay menu.

- This is currently hardcoded to use an Adobe Animate texture atlas.
- The character needs animations for leaping in, idle, confirm, and moving to character select. It also optionally has an idle and cartoon animation.
- Assets for the character's Freeplay skin and the backing card.

- This requires a variety of assets but can use Boyfriend's as a fallback.
- NOTE: This is currently hardcoded to BF or Pico.
- Assets for the character's animations in the Results screen.

- Each rank has its own animation and music, but animations can be reused between ranks and results themes can fall back to the default.
- Rank animations are Loss, Good, Great, Excellent, Perfect, and Perfect Gold (the base game uses the same animation for Perfect and Perfect Gold)
- Each also can take its own music, but you can reuse Boyfriend's as a good placeholder.
Expand Down Expand Up @@ -196,51 +205,68 @@ A custom playable character requires creating a new JSON file in the `data/chara
```

The available fields are:

- `version`: The version number for the Playable Character data file format. Leave this at `1.0.0`.
- `name`: The readable name for the character, used internally.
- `ownedCharacters`: The list of [Characters](../03-custom-characters/03-00-custom-characters.md) this character owns.
- `ownedCharacters`: The list of [Characters](../Introduction/3.CustomCharacters.md) this character owns.

- When determining which songs to display in Freeplay, the game checks for any songs where the player character is in this list and displays those. Songs where the player character is in another array are not displayed.
- `showUnownedChars`: If this value is `true`, then songs whose player character is not in any `ownedCharacters` list will be displayed for this character.
- `unlocked`: Whether the character is unlocked.
- Create a scripted class for this playable character and override `isUnlocked():Bool` to make this conditional. See [Scripted Playable Characters](21-scripted-classes\21-10-scripted-playable-characters.md)

- Create a scripted class for this playable character and override `isUnlocked():Bool` to make this conditional. See [Scripted Playable Characters](../Advanced/5.ScriptedPlayableCharacters.md)
- `freeplayStyle`: The ID for a Freeplay style to display.

- You can use `"bf"` here to use Boyfriend's Freeplay style as a default, or create a new JSON file in the `data/ui/freeplay/styles` folder (copy the Pico one and edit that).
- `freeplayDJ`: Data for how the character displays as the DJ in the Freeplay menu.
- `charSelect`: Data for how the character displays in the Character Select menu.
- `results`: Data for how the character displays in the Results screen.

Freeplay DJ data is structured like so:

- `assetPath`: The folder where the Animate Atlas for this character is located, relative to the `images/` folder.

- Note that Sparrow atlases are not supported for Freeplay animations.
- `animations`: A list of animation data for the character.

- Valid animation names include `intro` `idle` `idleEasterEgg` `confirm` `fistPump` `loss` `charSelect` and `
- `charSelect`: A structured data object containing:

- `transitionDelay`: A duration (in seconds) between when the character's transition to Character Select starts and the camera starts to fade.
- `fistPump`: A structured data object containing:

- `introStartFrame` The frame number in the `fistPump` animation where the intro animation (which loops until the rank slams down) starts.
- `introEndFrame` The frame number in the `fistPump` animation where the intro animation ends.
- `loopStartFrame` The frame number in the `fistPump` animation where the follow-up animation starts.
- `loopEndFrame` The frame number in the `fistPump` animation where the follow-up animation ends.

- Use `-1` to use the last frame of the specified frame label.
- `introBadStartFrame` The frame number in the `loss` animation where the intro animation starts.
- `introBadEndFrame` The frame number in the `loss` animation where the intro animation ends.
- `loopBadStartFrame` The frame number in the `loss` animation where the follow-up animation starts.
- `loopBadEndFrame` The frame number in the `loss` animation where the follow-up animation ends.

Character Select data is structured like so:

- `position`: The preferred grid square for the character in the Character Select grid.

- `0` represents the top left, `3` represents the middle left, and `8` represents the bottom right.
- Characters are evaluated alphabetically, and if the slot is already occupied, they will be shifted over until they fit.
- At time of writing (v0.5.1) only 9 total characters can fit in the grid.
- `gf`: (NEW with v0.5.1) A structured data object containing:

- `assetPath`: The folder where the Animate Atlas for this character is located, relative to the `images/` folder.

- Note that Sparrow atlases are not supported.
- `animInfoPath`: A path to a Flash JSFL file describing character sliding movement.
- `visualizer`: Whether the character is hooked up to display a visualizer (like Nene's ABot).

- Check the Nene Character Select FLA to see how to implement this.

Results data is structured like so:

- `music`: A structured data object containing:

- `PERFECT_GOLD`: The path to a music track in the `music/` folder. Played during the Perfect rank animation with all SICKs.
- `PERFECT`: The path to a music track in the `music/` folder. Played during the Perfect rank animation.
- `EXCELLENT`: The path to a music track in the `music/` folder. Played during the Excellent rank animation.
Expand All @@ -250,6 +276,7 @@ Results data is structured like so:
- Make sure to include a metadata file in the folder to tell the game what BPM the song is, and how to loop it.
- Include a variation of the track with the suffix `-intro.ogg` to play that track once before playing the main music track.
- `perfect`: An array of animation data structures, describing the animation played when the player gets a Perfect rank.

- Data is in the form of an array of animation objects.
- You can use Sparrow animations or `animateatlas` sprites. Use `renderType` to tell the game which one to use.
- Use `loopFrame` to tell the game which frame to start looping at, or set `looped` to `"false"` to just play the animation once.
Expand All @@ -258,6 +285,7 @@ Results data is structured like so:
- `good`: Data for the animation played when the player gets a Good rank.
- `loss`: Data for the animation played when the player gets a Loss rank.
- `perfectGold`: Data for the animation played when the player gets a Perfect rank with all SICKs.

- In the base game, this is just the same data as `perfect`, but you can make it different if you like.

[^picosource]: <https://github.com/FunkinCrew/funkin.assets/blob/main/preload/data/players/pico.json>
Expand Down
4 changes: 4 additions & 0 deletions assets/content/cookbook/Intermediate/2.CustomNotestyles.md
Original file line number Diff line number Diff line change
Expand Up @@ -195,6 +195,7 @@ Below is the "funkin" (aka the default) note style json file `assets/data/notest
```

There is quite a lot to unravel, let's break it all down.

- `version`: The version number for the Note Style data file format. Leave this at `1.0.0`.
- `name`: The readable name for the note style, used in places like the Chart Editor.
- `author`: The author of the note style, aka the artist who created the assets.
Expand All @@ -203,6 +204,7 @@ There is quite a lot to unravel, let's break it all down.
- See [list of assets](#note-style-assets) that you can provide the data for.

Asset data is structured like so:

- `assetPath`: The main asset path to use for this asset.
- `scale`: Specify the size of the asset relative to the original size. For example, `2.0` makes the sprite twice as big. Defaults to `1.0` if unspecified.
- `offsets`: Some animations may need their positions to be corrected relative to the idle animation.
Expand All @@ -211,6 +213,7 @@ Asset data is structured like so:
- `data`: The structure of note style asset data objects that depends on the asset you are going to edit.

Note Style Asset data is structured like so:

- For `note`: List of animation data for the `left`, `down`, `up` and `right` arrows.
- For `noteStrumline`: List of animation data for each direction and it's variations, such as `<direction>Static`, `<direction>Press`, `<direction>Confirm`, `<direction>ConfirmHold` replacing `<direction>` with it's each and every corresponding direction.
- As you may see from the [example](#note-style-data)[^notestylesource] that was given, animation data for the `confirm` and `confirmHold` match up, however you can make it have unique animations.
Expand All @@ -221,6 +224,7 @@ Note Style Asset data is structured like so:
- `enabled`: Specify whether to display the asset. Optional, defaults to `true`.

Animation data is structured like so:

- `prefix`: The animation name as specified by your spritesheet.
- For Sparrow or Packer, check inside the data file to see what each set of frames is named, and use that as the prefix, excluding the frame numbers at the end.
- For Animate Atlases, use either the frame label or the symbol name of the animation you want to play.
Expand Down
10 changes: 6 additions & 4 deletions assets/content/cookbook/Intermediate/3.CustomStickerPacks.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,15 +33,17 @@ Below is the "default" sticker pack JSON file `assets/data/stickerpacks/default.

Let's break it all down.
- `version`: The version number for the Sticker Pack data file format. Leave this at `1.0.0`.
- This will increase if the data file format changes, and tell the game whether additional processing needs to be done for backwards compatibility.

- This will increase if the data file format changes, and tell the game whether additional processing needs to be done for backwards compatibility.
- `name`: The readable name for the sticker pack, used in places like the Chart Editor.
- `author`: The author of the sticker pack, aka the artist who created the assets.
- `stickers`: A list of all the paths for all the stickers to use, as strings.
- You cannot currently specify any additional arguments, such as scale, offsets, texture smoothing, or animations.

- You cannot currently specify any additional arguments, such as scale, offsets, texture smoothing, or animations.

# Modifying an Existing Sticker Pack

You can use the [JSONPatch](../10-appending-and-merging-files/10-02-merging-files.md) feature to add or remove stickers from an existing sticker pack.
You can use the [JSONPatch](../Introduction/5.AppendingAndMerge.md#merging) feature to add or remove stickers from an existing sticker pack.

For example, to add to Boyfriend's standard sticker pack, you can use the following JSON Patch file (placed in `mods/mymod/_merge/data/stickerpacks/standard-bf.json`, use a different file path to patch a different sticker pack):

Expand All @@ -56,7 +58,7 @@ For example, to add to Boyfriend's standard sticker pack, you can use the follow

There are two ways the game defines a given sticker pack to be used:

- Each [Playable Character](../05-custom-playable-characters/05-00-custom-playable-characters.md) defines the `stickerPack` variable, which specifies the sticker pack to be used by songs containing that character. For example, `bf` uses the `standard-bf` sticker pack. You can define a sticker pack to be used for your custom playable character by setting the `stickerPack` value, or modify which sticker pack is used by other playable characters by using [JSONPatch](../10-appending-and-merging-files/10-02-merging-files.md) to modify the `stickerPack` value of that character.
- Each [Playable Character](1.CustomPlayableCharacters.md) defines the `stickerPack` variable, which specifies the sticker pack to be used by songs containing that character. For example, `bf` uses the `standard-bf` sticker pack. You can define a sticker pack to be used for your custom playable character by setting the `stickerPack` value, or modify which sticker pack is used by other playable characters by using [JSONPatch](../Introduction/5.AppendingAndMerge.md#merging) to modify the `stickerPack` value of that character.
- Each song has a value in its metadata to define which sticker pack is used. Set the `playData.stickerPack` on a song (or use JSONPatch to modify metadata of an existing song) to override which sticker pack it uses.

The game checks and uses sticker packs in this order:
Expand Down
Loading