The Character Name is what gets shown on the Voice Select Screen.

Your character’s Portrait needs to either be a PNG image or a Live2D rig.

In BBY DON'T HURT ME, a Live2D portrait consists of 4 files:

.models.json file

.moc3 file

Image texture file (usually a .png)

.motion3.json file

A Typical Live2D portrait is a folder with the following file structure and looks like this:

character

├octavix.model3.json // Description of the files used in the rig

├octavix.png // Cutout images making out the rig

├octavix.motion3.json // Animations

└octavix.moc3 // Binary object file

These files are usually generated when you save or export a project in the Live2D Cubism editor. As such, this guide will not go into detail on how to generate these files. That being said, a typical .model3.json file would look something like this.

Note that there is at least 1 group in “Motions”, which has at least 1 entry that points to the .motion3.json file and has a “MotionSync” of “Basic_CRI”.

This guide will not provide any instruction on how to set up your own Live2D character.

Background Images will be shown in the, well, background of the Interview Mode.

Notification Icon is an optional image that will appear when the character is speaking in Desktop Mode. 

# WHAT IS A .CSV?

In BBY DON’T HURT ME, our dialogue data is stored in the form of a CSV, which stands for Comma Separated Value file. We don’t advise trying to edit these by hand. The best way to modify a CSV file is to use a spreadsheet editor, such as Microsoft Excel or Google Sheets. 

You can create one yourself, or simply modify our template which contains an example. You can find here.

# COLUMN 1: TAG

The first column is the Tag. This is a string that uniquely identifies the voice line. The tag itself is broken up into a number of sections, separated by “_”s:

Finally, is the number, such as “01”. This is simply the sequence of the voice line and is necessary for there to be multiple lines in one category.

Pooled Tags support numbers, but special ones do not. Special Tags are used for specific purposes, such as special progression icons and minigame lines.

# COLUMN 2: CHARACTER

The second column is your character. This is what determines what shows up in the nametag section when the character speaks.

# COLUMN 3: NOTES

The third column is the Notes section. This does nothing and can be used to add notes for how you want to voice your character.

# COLUMN 4: THE DIALOGUE

The fourth column is the dialogue text. This is used to provide subtitles and supports \n to create newlines and $emphasis$ tags for red, shaky text.

# COLUMN 5: NEWLINE TIMINGS

The fifth column is optional and it is the newline timings. This is a comma-separated list of numbers (No comma is needed if you only have a single timing) and lets you know how long in seconds from the start of the audio clip to advance to the next line. A line can have any number of newlines in it. This is not strictly necessary to have - newlines can be automatically advanced even without using custom timings, but it will make the audio and subtitles work much more nicely together.

This screen is used to upload music data. You can only add one album using the creator, which needs a name and tracks. You will need to name each track and set its BPM, which you will need to know.

Default character noises are used if your character lacks voiced lines.

For a voice line to be played, it needs to have the same file name as its corresponding entry tag; see the CSV section.

These tags sit at the top of the file and define the package identity.

1. api-version: Always set this to 1.0. This tells the game loader which version of the BBYAML system you are using.

2. name: The human-readable name of your package (e.g., "Octavix Expansion"). If omitted, the game uses the folder name.

3. short_name: An optional abbreviated name for internal use.

4. version: The version number of your specific mod (e.g., 0.1.0).

5. age_rating: An integer (e.g., 18). This marks the content rating and ensures sensitive scenes are handled correctly based on user settings.

The voice_select block allows you to completely restyle the character selection menu when your package is highlighted.

backgrounds: A list of images to cycle through in the background.

path: The location of the image file.

name: Optional display name for the background.

decor: Controls the foreground UI elements.

corner_bars: Configures the stylized aesthetic bars in the bottom left.

sep: Pixels of separation between bars.

trans_time: How long the animation takes to fill the bars.

bars: A list defining each individual bar's color (Hex code), width, and height.

corner_icon: The rotating icon above the scrolling bar. Define the path, height, and width.

The music_tracks block defines the soundtrack included in your mod.

collections: Music is grouped into categories (collections).

id: Unique identifier for the category.

name: Display name.

icon: The logo for the category (includes path, height, and width).

tracks: The actual song data.

id & title: Identification and display name.

audio: The path to the audio file.

bpm: The Beats Per Minute. This is critical for game sync.

bpm-offset: Optional delay in seconds to align the beat grid.

1. id: The unique ID for the character.

2. name: The full display name.

3. lines: The path to the CSV file containing dialogue (as described in the CSV Documentation).

4. lines-audio: The directory path containing the .ogg or .wav files matching your CSV entrytags.

5. speech_pitch: (Optional) A value between 0.8 and 1.5. If audio files are missing, the game generates beeps; this controls their pitch.

6. placeholder_voice: (Optional) The timbre of the fallback beep sounds. Options are "light", "medium", "deep", or "none".

The portraits list defines the visuals. You can define multiple portraits; the game uses the first valid one found.

1. type: Set to "static" for images or "live2d" for animated rigs.

2. path: Path to the image or the Live2D .model3.json file.

3. type_data: Specific data for the type. For Live2D, include default_anim to specify which motion plays by default.

1. progression_icons: Path to a YAML file defining the icons that appear when the player does well or poorly.

2. endings: Links to YAML files for the "Love" (101+ temp) and "Toast" (151+ temp) cinematic endings.

Referenced by character.progression_icons, this file dictates the visual feedback during the interview.

good: A list of icons for positive feedback. Plays audio from the "mood_like" category.

bad: A list of icons for negative feedback. Plays audio from the "mood_hate" category.

special: Unique icons.

texture: Path to the icon image.

audio: A specific entrytag from your dialogue CSV (e.g., litany_mood_special_baton) that plays when this icon appears.

Referenced by character.endings, this file scripts the cinematic sequences.

Global Styles

cinema_bars_gradient: Defines the gradient colors (color_1, color_2) for the letterbox bars at the bottom of the screen.

Scenes

The scenes list plays sequentially. There are three main types of scenes:

# 1 - TEXT SCENE

This is a black screen with typewriter-style text.

1. text: The string to display. Supports BBCode.

2. silhouette: (Optional) Path to a silhouette image to display alongside the text (supports offset_x / offset_y).

3. ending_type: Defines the lighting mood ("love" or "toast").

4. voice_lines: An array of audio filenames (matching your CSV structure) that play during the text.

5. duration: How long the scene lingers after typing finishes.

# 2 - IMAGE SCENE

Displays full-screen panels or sequential images.

images: A list of image objects.

path: File path.

swoop_time: The timestamp (in seconds from scene start) when this specific image finishes its entry animation.

swoop_duration: How long the entry animation takes.

caption: Dialogue displayed at the bottom.

character_name: Name displayed above the caption.

# 3 - CAPTION CHANGE

Updates the text and audio without changing the visual images on screen.

1. caption: The new text to display.

2. voice_lines: Array of new audio files to play.