Skip to content

Commit a93d283

Browse files
EliteMasterEricEliteMasterEric
committed
Playable character JSON documentation
1 parent 35eb760 commit a93d283

File tree

2 files changed

+212
-2
lines changed

2 files changed

+212
-2
lines changed

‎src/05-custom-playable-characters/05-02-creating-a-playable-character.md

+210
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,210 @@
1+
# Creating a Playable Character
2+
3+
A custom playable character requires creating a new JSON file in the `data/characters` folder. Below is an example of Pico's character data file, from `assets/data/players/pico.json`[^picosource]
4+
5+
```json
6+
{
7+
"version": "1.0.0",
8+
"name": "Pico",
9+
"ownedChars": [
10+
"pico",
11+
"pico-playable",
12+
"pico-blazin",
13+
"pico-christmas",
14+
"pico-dark"
15+
],
16+
"showUnownedChars": false,
17+
"unlocked": true,
18+
"freeplayStyle": "pico",
19+
"freeplayDJ": {
20+
"assetPath": "freeplay/freeplay-pico",
21+
"text1": "PICO",
22+
"text2": "GOD DAMN HE DOWN ON THE NUT",
23+
"text3": "ZEBOIM DAMN IMA NUT",
24+
"fistPump": {
25+
"introStartFrame": 0,
26+
"introEndFrame": 4,
27+
28+
"loopStartFrame": 4,
29+
"loopEndFrame": -1,
30+
31+
"introBadStartFrame": 0,
32+
"introBadEndFrame": 0,
33+
34+
"loopBadStartFrame": 0,
35+
"loopBadEndFrame": -1
36+
},
37+
"charSelect": {
38+
"transitionDelay": 0.45
39+
},
40+
"animations": [
41+
{
42+
"name": "intro",
43+
"prefix": "pico dj intro",
44+
"offsets": [631.7, 362.6]
45+
},
46+
{
47+
"name": "idle",
48+
"prefix": "Pico DJ",
49+
"offsets": [625, 360]
50+
},
51+
{
52+
"name": "idleEasterEgg",
53+
"prefix": "Pico DJ afk",
54+
"offsets": [625, 360]
55+
},
56+
{
57+
"name": "confirm",
58+
"prefix": "Pico DJ confirm",
59+
"offsets": [625, 360]
60+
},
61+
{
62+
"name": "fistPump",
63+
"prefix": "pico cheer",
64+
"offsets": [975, 260]
65+
},
66+
{
67+
"name": "loss",
68+
"prefix": "Pico DJ loss",
69+
"offsets": [625, 360]
70+
},
71+
{
72+
"name": "charSelect",
73+
"prefix": "Pico DJ to CS",
74+
"offsets": [625, 360]
75+
}
76+
]
77+
},
78+
"charSelect": {
79+
"position": 3
80+
},
81+
"results": {
82+
"music": {
83+
"PERFECT_GOLD": "resultsPERFECT-pico",
84+
"PERFECT": "resultsPERFECT-pico",
85+
"EXCELLENT": "resultsEXCELLENT-pico",
86+
"GREAT": "resultsNORMAL-pico",
87+
"GOOD": "resultsNORMAL-pico",
88+
"SHIT": "resultsSHIT-pico"
89+
},
90+
"perfect": [
91+
{
92+
"renderType": "animateatlas",
93+
"assetPath": "shared:resultScreen/results-pico/resultsPERFECT",
94+
"zIndex": 500,
95+
"scale": 0.88,
96+
"offsets": [385, 82],
97+
"loopFrame": 91
98+
}
99+
],
100+
"excellent": [
101+
{
102+
"renderType": "animateatlas",
103+
"assetPath": "shared:resultScreen/results-pico/resultsGREAT",
104+
"zIndex": 500,
105+
"scale": 1.25,
106+
"offsets": [350, 25],
107+
"looped": true,
108+
"loopFrame": 32
109+
}
110+
],
111+
"great": [
112+
{
113+
"renderType": "animateatlas",
114+
"assetPath": "shared:resultScreen/results-pico/resultsGREAT",
115+
"zIndex": 500,
116+
"scale": 1.25,
117+
"offsets": [350, 25],
118+
"looped": true,
119+
"loopFrame": 32
120+
}
121+
],
122+
"good": [
123+
{
124+
"renderType": "animateatlas",
125+
"assetPath": "shared:resultScreen/results-pico/resultsGOOD",
126+
"zIndex": 500,
127+
"scale": 1.25,
128+
"offsets": [350, 25],
129+
"loopFrame": 41
130+
}
131+
],
132+
"loss": [
133+
{
134+
"renderType": "animateatlas",
135+
"assetPath": "shared:resultScreen/results-pico/resultsSHIT",
136+
"zIndex": 500,
137+
"offsets": [-185, -125],
138+
"loopFrame": 0
139+
}
140+
]
141+
}
142+
}
143+
```
144+
145+
The available fields are:
146+
- `version`: The version number for the Playable Character data file format. Leave this at `1.0.0`.
147+
- `name`: The readable name for the character, used internally.
148+
- `ownedCharacters`: The list of [Characters](03-custom-characters/03-00-custom-characters.md) this character owns.
149+
- 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.
150+
- `showUnownedChars`: If this value is `true`, then songs whose player character is not in any `ownedCharacters` list will be displayed for this character.
151+
- `unlocked`: Whether the character is unlocked.
152+
- 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)
153+
- `freeplayStyle`: The ID for a Freeplay style to display.
154+
- 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).
155+
- `freeplayDJ`: Data for how the character displays as the DJ in the Freeplay menu.
156+
- `charSelect`: Data for how the character displays in the Character Select menu.
157+
- `results`: Data for how the character displays in the Results screen.
158+
159+
Freeplay DJ data is structured like so:
160+
- `assetPath`: The folder where the Animate Atlas for this character is located, relative to the `images/` folder.
161+
- Note that Sparrow atlases are not supported for Freeplay animations.
162+
- `animations`: A list of animation data for the character.
163+
- Valid animation names include `intro` `idle` `idleEasterEgg` `confirm` `fistPump` `loss` `charSelect` and `
164+
- `charSelect`: A structured data object containing:
165+
- `transitionDelay`: A duration (in seconds) between when the character's transition to Character Select starts and the camera starts to fade.
166+
- `fistPump`: A structured data object containing:
167+
- `introStartFrame` The frame number in the `fistPump` animation where the intro animation (which loops until the rank slams down) starts.
168+
- `introEndFrame` The frame number in the `fistPump` animation where the intro animation ends.
169+
- `loopStartFrame` The frame number in the `fistPump` animation where the follow-up animation starts.
170+
- `loopEndFrame` The frame number in the `fistPump` animation where the follow-up animation ends.
171+
- Use `-1` to use the last frame of the specified frame label.
172+
- `introBadStartFrame` The frame number in the `loss` animation where the intro animation starts.
173+
- `introBadEndFrame` The frame number in the `loss` animation where the intro animation ends.
174+
- `loopBadStartFrame` The frame number in the `loss` animation where the follow-up animation starts.
175+
- `loopBadEndFrame` The frame number in the `loss` animation where the follow-up animation ends.
176+
177+
Character Select data is structured like so:
178+
- `position`: The preferred grid square for the character in the Character Select grid.
179+
- `0` represents the top left, `3` represents the middle left, and `8` represents the bottom right.
180+
- Characters are evaluated alphabetically, and if the slot is already occupied, they will be shifted over until they fit.
181+
- At time of writing (v0.5.1) only 9 total characters can fit in the grid.
182+
- `gf`: (NEW with v0.5.1) A structured data object containing:
183+
- `assetPath`: The folder where the Animate Atlas for this character is located, relative to the `images/` folder.
184+
- Note that Sparrow atlases are not supported.
185+
- `animInfoPath`: A path to a Flash JSFL file describing character sliding movement.
186+
- `visualizer`: Whether the character is hooked up to display a visualizer (like Nene's ABot).
187+
- Check the Nene Character Select FLA to see how to implement this.
188+
189+
Results data is structured like so:
190+
- `music`: A structured data object containing:
191+
- `PERFECT_GOLD`: The path to a music track in the `music/` folder. Played during the Perfect rank animation with all SICKs.
192+
- `PERFECT`: The path to a music track in the `music/` folder. Played during the Perfect rank animation.
193+
- `EXCELLENT`: The path to a music track in the `music/` folder. Played during the Excellent rank animation.
194+
- `GREAT`: The path to a music track in the `music/` folder. Played during the Great rank animation.
195+
- `GOOD`: The path to a music track in the `music/` folder. Played during the Good rank animation.
196+
- `SHIT`: The path to a music track in the `music/` folder. Played during the Loss rank animation.
197+
- Make sure to include a metadata file in the folder to tell the game what BPM the song is, and how to loop it.
198+
- Include a variation of the track with the suffix `-intro.ogg` to play that track once before playing the main music track.
199+
- `perfect`: An array of animation data structures, describing the animation played when the player gets a Perfect rank.
200+
- Data is in the form of an array of animation objects.
201+
- You can use Sparrow animations or `animateatlas` sprites. Use `renderType` to tell the game which one to use.
202+
- Use `loopFrame` to tell the game which frame to start looping at, or set `looped` to `"false"` to just play the animation once.
203+
- `excellent`: Data for the animation played when the player gets a Excellent rank.
204+
- `great`: Data for the animation played when the player gets a Great rank.
205+
- `good`: Data for the animation played when the player gets a Good rank.
206+
- `loss`: Data for the animation played when the player gets a Loss rank.
207+
- `perfectGold`: (NEW with v0.5.1) Data for the animation played when the player gets a Perfect rank with all SICKs.
208+
- In the base game, this is just the same data as `perfect`, but you can make it different if you like.
209+
210+
[^picosource]: <https://github.com/FunkinCrew/funkin.assets/blob/main/preload/data/players/pico.json>

‎src/SUMMARY.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -29,9 +29,9 @@
2929
- [Creating a Stage](04-custom-stages/04-01-creating-a-stage.md)
3030
- [Using a Stage in a Song](04-custom-stages/04-02-using-a-stage-in-a-song.md)
3131

32-
- [WIP: Custom Playable Characters](05-custom-playable-characters/05-00-custom-playable-characters.md)
32+
- [Custom Playable Characters](05-custom-playable-characters/05-00-custom-playable-characters.md)
3333
- [Required Assets](05-custom-playable-characters/05-01-required-assets.md)
34-
- [WIP: Implementing a Playable Character](05-custom-playable-characters/05-00-custom-playable-characters.md)
34+
- [Creating a Playable Character](05-custom-playable-characters/05-02-creating-a-playable-character.md)
3535

3636
- [Custom Note Styles](06-custom-notestyles/06-00-custom-notestyles.md)
3737
- [Creating a Note Style](06-custom-notestyles/06-01-creating-a-notestyle.md)

0 commit comments

Comments
 (0)