YoUwU Instructions

---

Welcome to YoUwU Novel Creations! This guide will walk you through everything you need to know. Thanks to our Project Template, starting your first visual novel is incredibly easy.

Step 1: Download and Unzip the Project Template

• On this page, find and click the download link for the "YoUwU Project Template.zip" file.
• Save the file to your computer and unzip it. This will create a folder containing the entire required directory structure and starter text files.

Step 2: Load Your New Project!

• Go to the main YoUwU Creations tool.
• Click the "Load Project Folder" button.
• In the file browser that appears, select the YoUwU Project Template folder you just unzipped.

That's it! The tool will load a simple, working "Hello World" project. Now you can explore the other topics in this guide to learn how to add your own art, characters, and dialogue.

The Project Template you downloaded contains a specific folder structure that the engine relies on to find your assets. Understanding this structure is the key to adding your own content.

Here is the layout of the template:

>>>>>>>>>>

My-First-Novel/
+-- Images/
| +-- Background/
| +-- Character/
| +-- FMV/
| +-- UI/
|
+-- Audio/
| +-- BGM/
| +-- SFX/
| +-- Voice/
|
+-- Text/
| +-- script.json
| +-- map.json
| +-- choices.json
|
+-- Saves/

<<<<<<<<<<

How to Add Your Own Art & Sound:

1. To add a character: Go into the /Images/Character/ folder and create a new folder with a lowercase name for your character (e.g., yuki). Place all their art inside this new yuki folder (e.g., happy.png, sad.png). You will then refer to them in the script with @char(yuki, ...)
2. To add a background: Go into /Images/Background/ and create a "zone" folder for your location (e.g., school). Place your background images inside that school folder. You will refer to them in the script with @bg(school, my_bg.jpg).
3. To add music or sound effects: Simply place your audio files into the /Audio/BGM/ or /Audio/SFX/ folders respectively.

Key Rule: The engine works by matching the lowercase names of your folders (yuki, school) and files (happy.png, my_bg.jpg) to the names you use in your script commands.

Your entire visual novel is controlled by three special text files that must be placed in your project's /Text/ folder. These files use a format called JSON, which has very strict rules about curly braces {}, quotes "", and commas ,. It's best to copy these examples exactly and only change the content inside the quotes.

You can create these files with any plain text editor, like Notepad or VS Code.

This file is the simple roadmap for your game. It tells the engine two things: where to start, and what scene comes next in a linear sequence.

Purpose: Defines the starting scene and simple, linear scene connections.

Starter Code: Copy this into a new file and save it as map.json in your /Text/ folder.

{
"startScene": "Intro_Scene",
"connections": {
"Intro_Scene": "Second_Scene",
"Second_Scene": null
}
}

• startScene: This is the ID of the very first scene to load when the game begins.
• connections: This connects scenes. In this example, after "Intro_Scene" ends, it will automatically load "Second_Scene". When "Second_Scene" ends, it connects to null, meaning the story branch ends there. If a scene leads to a choice, you should also set its connection to null.

This file holds all the player decisions. Each choice has a unique ID that you can call from your script.

Purpose: Manages all player choices and their resulting scenes.

Starter Code: Copy this into a new file named choices.json.

{
"Greeting_Choice": {
"options": [
{
"text": "Say something nice.",
"targetScene": "Nice_Reply_Scene"
},
{
"text": "Be a little mean.",
"targetScene": "Mean_Reply_Scene"
}
]
}
}

• In this example, "Greeting_Choice" is the ID. When your script calls CHOICE:Greeting_Choice, these two buttons will appear. Clicking the first button will load "Nice_Reply_Scene", and so on.

This is the heart of your novel. It contains all the scenes, which are made up of dialogue lines and commands. It's a big file where each "key" is a Scene ID that matches the IDs used in your map.json and choices.json.

Purpose: Holds all the dialogue and action commands for every scene.

Starter Code: Copy this into a new file named script.json.

{
"Intro_Scene": {
"dialogue": [
"@bg(school, day_clear.jpg)",
"@char(yuki, left1, happy, enter, left)",
"Yuki: This is the first line of my visual novel!",
"Yuki: This is the second line.",
"CHOICE:Greeting_Choice"
]
},
"Nice_Reply_Scene": {
"dialogue": [
"Yuki: You chose the nice option. Thanks!",
"@goto(Second_Scene)"
]
},
"Mean_Reply_Scene": {
"dialogue": [
"Yuki: You chose the mean option. Ouch.",
"@goto(Second_Scene)"
]
},
"Second_Scene": {
"dialogue": [
"@char(yuki, left1, normal)",
"Yuki: Now we are on the second scene, no matter what you chose.",
"SYSTEM: The End."
]
}
}

• This example contains all the scenes needed to make our sample map and choices work. Notice how the scene IDs ("Intro_Scene", "Nice_Reply_Scene", etc.) match the other files perfectly. The dialogue is an array [] of strings "", where each string is a line of dialogue or a command.

Commands are special instructions in your script.json file that make things happen, like changing the background, moving a character, or playing a sound. All commands start with an @ symbol.

Command: @bg(zone, filename)

• Purpose: Changes the background image.
• Parameters:
  
  • zone: The name of the folder inside /Images/Background/ where your image is located (e.g., school).
  • filename: The full name of the image file (e.g., day_clear.jpg).
• Example:
  @bg(school, day_clear.jpg)

Command: @goto(SceneID)

• Purpose: Immediately stops the current scene and jumps to a new one.
• Parameters:
  
  • SceneID: The exact ID of the scene you want to jump to from your script.json.
• Example:
  @goto(Chapter_2_Start)

Command: @wait(seconds)

• Purpose: Pauses the game for a set amount of time before automatically advancing to the next line. This is great for dramatic timing.
• Parameters:
  
  • seconds: The number of seconds to wait (can be a decimal, like 1.5).
• Example:
  Yuki: ...[@wait(2.5)]

Command: @char(charId, slotId, expression, effect, facing, yPos, animType, animSpeed, animRange)

• Purpose: Controls every aspect of a character on screen. You don't have to use all parameters every time.
• Parameters:
  
  1. charId: The character's ID (the lowercase folder name, e.g., yuki).
  2. slotId: Where they appear. (left1, left2, left3, right1, right2, right3).
  3. expression: The name of the character's image file without the .png (e.g., happy).
  4. effect: enter (to appear), exit (to disappear), or hold (to just change expression/position while on screen).
  5. facing: (Optional) left or right.
  6. yPos: (Optional) Vertical position. 0 is the default. -10 moves down, 10 moves up.
  7. animType: (Optional) loop (for a bobbing effect) or oneshot (for a single movement like falling).
  8. animSpeed: (Optional) For animations. A number from 1 (very slow) to 10 (very fast).
  9. animRange: (Optional) For animations. The start and end Y-positions, like 0_to_-100.

• Simple Example (Character Enters):
  @char(kenji, right1, happy, enter, right)
• Complex Example (Character Falls Down):
  Yuki: [@char(kenji, right1, surprised, hold, right, 0, oneshot, 6, 0_to_-50)] Oh no!

Command: CHOICE:ChoiceID

• Purpose: This isn't an @command, but a special line that pauses the game and displays a set of buttons for the player to click.
• Parameters:
  
  • ChoiceID: The exact ID of the choice you defined in your choices.json file.
• Example:
  CHOICE:Greeting_Choice

Pro-Tip: The Creator Mode has a powerful editor that can build the complex @char commands for you! See the "Creator Mode Guide" topic for more information.

Creator Mode is designed to take the guesswork out of complex commands, especially for character placement and animation. It provides a visual interface to build commands that you can then copy and paste directly into your script.json file.

Here is the recommended workflow:

• After loading your project folder, click the "Creator" button in the top bar.
• This will overlay the creator panels on the right side of the screen.

• In the "Scene Controls" panel, use the drop-down menu to select the scene you want to work on.
• The contents of that scene's script will appear in the "Script Viewer" panel below, giving you a quick reference.

• To begin editing, click directly on one of the six character slots in the main viewport. You will see it become highlighted.
• This will immediately populate the "Properties" panel with all the controls for that specific slot.

This is where the magic happens. Use the simple controls to build a complex @char command visually.

• Character: Select which character you want in the slot (e.g., yuki).
• Expression: Choose one of that character's available expressions (e.g., happy).
• Facing: Toggle whether the character should face left or right.
• Vertical Position: Set a static Y-position for the character.
• Animation Type: Choose between None, a looping Bob effect, or a One-Shot movement (like a jump or fall). If you select an animation, more controls will appear.
• Animation Controls: Fine-tune the animation's speed and its start/end points.

• As you change the properties, you will see the "Generated Command" box at the bottom of the panel update in real-time.
• Once you are happy with the visual state you've created, click the "Copy Command" button.
• Go to your script.json file in your text editor and paste this command where you need it!

Important Note: The command generator always uses the hold effect (e.g., @char(..., hold, ...)). For the first time a character appears in a scene, you will need to manually change hold to enter. If you want them to disappear, change hold to exit.

Here are answers to some frequently asked questions and tips for sharing your projects.

Q: Why does saving a game make me download a file?

• A: For security reasons, a website script (like this tool) cannot directly write files to your computer. The "Manual Save" feature works by generating a save.txt file and having your browser download it. You must then manually move that downloaded file from your "Downloads" folder into your project's /Saves/ folder for the tool to be able to load it later.

Q: Does the "Auto-Save" feature have the same issue?

• A: No! The auto-save uses your browser's internal localStorage. It's designed to protect you if you accidentally close the tab or your browser crashes. However, this save data is tied to your specific browser and cannot be moved or shared. It's for crash recovery only.

Q: Why isn't my character's animation working?

• A: Check your @char command! Ensure you've set the animType parameter to either loop or oneshot. If you have, make sure you've also defined the animSpeed and animRange (e.g., 0_to_-50).

The "AI Helper" panel in Creator Mode is a powerful tool to accelerate your writing process.

1. Click the "Copy Rules for AI" button.
2. Go to an AI Chatbot (like ChatGPT, Claude, etc.) and paste the rules into the chat.
3. After pasting the rules, give the AI your story prompt. For example: "Write a scene with the ID Scene_Apology where Kenji apologizes to Yuki."
4. The AI will respond with a block of JSON code. Copy that entire code block.
5. Return to the YoUwU tool, paste the code into the "Paste AI Response Here" box, and click "Apply AI Script".
6. The new scene will be added to your project instantly!

The best way to share your creation with others is to compress the entire project into a single file.

1. Find your main project folder (e.g., "My-First-Novel") on your computer.
2. Right-click on the folder and choose "Compress to ZIP file" (or "Send to -> Compressed (zipped) folder" on Windows).
3. This will create a single .zip file of your entire project, including all images, sounds, scripts, and even your manual saves!
4. You can then share this .zip file with others, and when they unzip it, they will have the complete, ready-to-load project.