Commit 9ff3da6f authored by cobaltcore's avatar cobaltcore
Browse files

Document JSON->YAML transition, tools and additional help

parent dd3f24ce
# 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.
=== "JSON"
```json
{
"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"
}
```
=== "YAML"
```yaml
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":
=== "JSON"
```json
{
"name_color": "#915f40",
"name": "Eliza\u2122",
"voice": "girl",
"eye_line": 0.195,
"scale": 0.6,
"poses": {
"a": {
"facing": "right"
}
}
}
```
=== "YAML"
```yaml
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](https://git.student-transfer.com/vncollab/st/blob/master/tools/json2yaml.py) 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](https://www.json2yaml.com/) 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`.
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment