Porting v4 Scenario Data to v5

With v5 we introduced a new format for all of our data files: YAML. While we remain backwards compatible with JSON for the time being, it is recommended to move all data files to this new format going forward. This guide will describe the why's, what's and how's of moving your data over quickly and efficiently.

What does this affect?

This change will affect all data files that Student Transfer uses. What are "data files"? Well, effectively all files that we load to supply additional data. Basically everything that was previously a JSON file is being moved to YAML. This chiefly includes character data (character.json) and scenario data (scenario.json).

Why a new format?

This move is largely motivated by the desire to make things easier on ourselves and on scenario authors. JSON has several peculiarities that can make it unintuitive or bothersome to work with, namely:

• It requires that everything that's not a number be put into "quotes", which is unnecessary and tedious for the user
• It requires several levels of brackets, which can be confusing for newcomers
• The rules about where commas can and can not be placed are weird and don't make much sense unless you look into it, which nobody does

All of these combined lead to a sub-par user experience, especially for newcomers, which forces many people to rely on external tools such as Linters to validate and check their JSON files for non-obvious errors.

Moving to YAML would fix all of these problems as this format exposes several desirable traits:

• Strings can be specified without quotes unless they contain special characters (AKA non-ASCII)
• Variable names can always be specified without quotes
• No brackets necessary
• No comma-witchery
• Parsing of primitive types is more forgiving
• The syntax highlighting in supported editors is a bit nicer

To exemplify the benefits, let us look at a real-world example. This below is the scenario.json file from the example scenario. Switch the tab to "YAML" to see what it looks like in the new format.

JSONYAML

{
    "author": "Jcjace45, CobaltCore",
    "title": "Writing Scenarios in Ren'Py",
    "description": "A quick and dirty guide to creating scenarios. For more information, read the official guide.",
    "label": "scenario_example",
    "tags": ["official", "tutorial", "guide"],
    "version": "2.0.0",
    "hook_hash": "a757c4bc",
    "prefix": "example"
}

author: 'Jcjace45, CobaltCore'
description: A quick and dirty guide to creating scenarios. For more information, read the
  official guide.
hook_hash: a757c4bc
label: scenario_example
prefix: example
tags:
  - official
  - tutorial
  - guide
title: Writing Scenarios in Ren'Py
version: 2.0.0

Note how we got rid of all the bothersome quoting, commas and brackets. Nice, isn't it?

Let's look at an example of character data. The below is also taken from the example scenario, specifically from the custom character "Eliza":

JSONYAML

{
    "name_color": "#915f40",
    "name": "Eliza\u2122",
    "voice": "girl",
    "eye_line": 0.195,
    "scale": 0.6,
    "poses": {
        "a": {
            "facing": "right"
        }
    }
}

display_name: "Eliza™"
eye_line: 0.195
name_color: "#915f40"
poses:
  a:
    facing: right
scale: 0.6
voice: girl

As you can see the result is smaller and much cleaner overall, which we think will make it easier for scenario authors to write character and scenario definitions.

How do I actually do this?

Of course the question that you've all been asking in your heads is:

"How do I move all my shit to this new format without doing any work?"

- Author in Despair

This is understandable, especially if you have dozens or even hundreds of custom characters, which would take ages to convert by hand.

Fear not, though, for we provide a tool and a capable person who knows how to use it to batch-convert all your JSON files to YAML in one fell swoop. Since it is a Python script, it can be somewhat difficult to set up, so if you don't feel like doing that, you can hit up cobaltcore#0045 on Discord (or on the TFGS forums via private message) to have them do it for you.

Alternatively, if you only have one or two files you need to convert, you can use a simple online converter to do it. Simply plug in the contents of your existing JSON file on the left, copy the converted YAML from the right and paste it back into your exitsing JSON file, overwriting its contents. After saving and closing the file, you can simply rename the extension from .json to .yml and you're good to go! As an example, the file character.json would have to be renamed to character.yml.

---

Last update: August 3, 2021