Small Guide

Migrating Your Scenario to the Next Release of StudentTransfer

Believe it or not, a release might actually be happening at some point in the future. Since Halloween has passed and the need for evil surprises with it, we decided it would be a good idea to give scenario authors a heads-up on what scenarios in v4 of StudentTransfer will be all about. This way, authors can already start porting their scenarios so they are ready for primetime as soon as the actual release hits.

Since the guides I write tend to be longer than the great wall of China had it taken an entire bottle of viagra, here's a TL;DR for your convenience:

The Good:
- Your story files will stay mostly untouched.
- Assets added via the recommended method in the official guide will remain functional. This applies to Music, Sound Effects, Backgrounds and the miscellaneous images in the "assets" folder that nobody uses.

The Bad:
- Assets of any kind added via hardcoded paths in your story file will break.
- Custom characters will now be prefixed with your scenario prefix, meaning you will have to update their names in your story files.
- Characters from the base game can not be extended anymore. If you do want to do that, please copy the entire character and make any changes you require to your local copy in your scenario. This helps keep things consistent and somewhat prevents dependency chains.

The Ugly:
- We've moved to an entirely different file structure for characters. All custom characters will have to be ported to this new structure before your scenario will run.

It would be advisable to continue reading after this TL;DR since we'll now be explaining how you can effectively torture yourself for a few hours. So, giddy up while I grab the thumb screws!

Why a new character format?
Convenience, mostly. After the initial bump, that is.
The move to the new format brings one big advantage with it: Modularisation. Whereas previously character information was strewn about several different files and folders it is now all neatly contained within one directory. This allows us to do many cool and interesting things (disclaimer: only cool and interesting if you are a programmer).
From our side, we now have more control over how characters are loaded and how we handle them ingame. Also, we got to add [url=https://stgit.ddns.net:1234/vncollab/st/blob/code_v4_consolidation/game/character.py#L65]this monstrosity[/url] as an (April fool's) surprise for future coders.
From your side, adding new characters is now easier (fingers crossed) and less error-prone.

What does it look like?
Let's take a look at a very simple character first, Yui. The following snippets have been shortened for your convenience by removing some face files, but other than that they are actual snapshots from what the base game will look like.
[spoiler]
[code]
yui/
├── a/
│   ├── faces/
│   │   ├── blush/
│   │   │   ├── 0.png
│   │   │   ├── 1.png
│   │   └── face/
│   │       ├── 0.png
│   │       ├── 1.png
│   └── outfits/
│       ├── casual.png
│       ├── gym.png
│       ├── nude.png
│       └── uniform.png
├── b/
│   ├── faces/
│   │   ├── blush/
│   │   │   ├── 0.png
│   │   │   ├── 1.png
│   │   └── face/
│   │       ├── 0.png
│   │       ├── 1.png
│   └── outfits/
│       ├── casual.png
│       ├── nude.png
│       ├── swimsuit.png
│       ├── swimsuit_covered.png
│       └── uniform.png
└── character.json
[/code]
[/spoiler]

What you can see in this "graphic" is that essentially, the flat file structure we had before has been pulled out into multiple sub-directories. Basically we have traded super-long, unreadable filenames for shorter, much easier to understand directories and simple filenames. Most of the data is now inferred by StudentTransfer from the folder structure itself and it is much more logically structured. We hope that this change makes it easier for people to understand even the more complex capabilities such as mutations, in the best case simply by looking at the file structure.

The below is all the metadata you need for Yui. Only the most perceptive of you will notice the almost uncanny resemblance to the previous format.
[spoiler]
[code]
{
    "name_color": "#77569c",
    "eye_line": 0.04,
    "scale": 0.9
}
[/code]
[/spoiler]

And now, for something a bit more complex. Cornelia is our most complicated character at the moment, so watch what happens when we apply the new character format:
[spoiler]
[code]
cornelia/
├── a/
│   ├── faces/
│   │   ├── blush/
│   │   │   ├── 0.png
│   │   │   ├── 1.png
│   │   ├── face/
│   │   │   ├── 0.png
│   │   │   ├── 1.png
│   │   └── mutations/
│   │       └── twintails/
│   │           ├── blush/
│   │           │   ├── 0.png
│   │           │   ├── 1.png
│   │           │   └── makeup/
│   │           │       ├── 0.png
│   │           │       ├── 1.png
│   │           └── face/
│   │               ├── 0.png
│   │               ├── 1.png
│   │               └── makeup/
│   │                   ├── 0.png
│   │                   ├── 1.png
│   └── outfits/
│       ├── casual.png
│       ├── costume/
│       │   ├── bottle/
│       │   │   ├── off.png
│       │   │   └── on.png
│       │   └── costume.png
│       ├── nude.png
│       ├── pajamas.png
│       ├── uniform.png
│       └── uniform_b.png
├── b/
│   ├── faces/
│   │   ├── blush/
│   │   │   ├── 0.png
│   │   │   ├── 1.png
│   │   ├── face/
│   │   │   ├── 0.png
│   │   │   ├── 1.png
│   │   └── mutations/
│   │       └── twintails/
│   │           ├── blush/
│   │           │   ├── 0.png
│   │           │   ├── 1.png
│   │           │   └── makeup/
│   │           │       ├── 0.png
│   │           │       ├── 1.png
│   │           └── face/
│   │               ├── 0.png
│   │               ├── 1.png
│   │               └── makeup/
│   │                   ├── 0.png
│   │                   ├── 1.png
│   └── outfits/
│       ├── casual.png
│       ├── cheer.png
│       ├── cheer_inverted.png
│       ├── costume/
│       │   ├── bottle/
│       │   │   ├── off.png
│       │   │   └── on.png
│       │   └── costume.png
│       ├── nude.png
│       ├── pajamas.png
│       ├── swimwear.png
│       ├── uniform.png
│       ├── uniform_b.png
│       └── yukata.png
└── character.json
[/code]
[/spoiler]

This already looks a bit more complicated but if you take a closer look, you'll notice that it is mostly the same as for Yui. This structure especially showcases how mutations work, as they are basically a priority set of images that gets chosen over the default one when a specific outfit is active.

And this is all the metadata you need for Cornelia. You can see that we have to enter a bit more information since we have a few special cases in here, e.g. sprites facing the wrong direction as well as several mutations.
[spoiler]
[code]
{
    "name_color": "#fbca86",
    "voice": "child",
    "eye_line": 0.1,
    "scale": 0.9,
    "poses": {
        "b": {
            "facing": "right"
        }
    },
    "mutations": {
        "twintails": ["casual", "costume", "swimwear", "uniform", "uniform_b", "yukata", "cheer", "cheer_inverted"]
    }
}
[/code]
[/spoiler]

There is one important piece of information you should keep in mind: The new format does not add or remove any images from custom characters, it only rearranges them. The only thing that has changed with the new v4 format is the layout of the files on disk. Any existing character that works in StudentTransfer v3.1 will work in v4 just by rearranging the existing files.

If you want to take a look at the new structure yourself, you can download the two example characters here: [url=https://mega.nz/#!Qk5kXaaB!6a3jflt8mTyd0lnXOnKsc7QSKXG53HB3kH_KN9RTr5A]Yui[/url] and [url=https://mega.nz/#!MoxmVAST!jGI9K_lL0AwBjOxDXWA-JASFmAA_GlRebJy2bQ7Jl1s]Cornelia[/url].

How do I port an existing character to the new format?
Well, let me start at the top.
In the beginning, there was light.
This was then quickly followed by despair as scenario authors realized they'd have to move and rename thousands of files manually 'til the blood ran dry of their battered hands and their tears of agony had filled the sea of sorrows to the brink. But they feared not, for the ST dev-team stood steadfast against the dying of the light, bringing them a tool to automatically convert all of their custom characters for them!

Introducing: "Harry Porter and the Shimmer of Hope"

This little utility script, dubbed "Harry Porter" because we all appreciate a good pun, will, once pointed at a character directory of v3-style characters, automatically port all of them to the new format, without you having to lift a finger. If you have the character.rpy file handy, it'll even port most of the metadata! It'll convert individual characters as well as entire directories of characters so it really is a one-stop-shop solution.

Now, the caveats:
This tool is a command-line script that requires Python, so unless you have Python installed and correctly set up, you won't be able to use this script.
If you don't want to go through the whole shebang of installing Python on Windows, you can simply hit me up via PM here or on Discord and I'll convert your characters for you, free of charge no less! Since this is a one-time occurence, this shouldn't be too much of a problem, hopefully.

For those brave few souls that actually want to run the script themselves, you can find installation and usage instructions in the [url=https://stgit.ddns.net:1234/vncollab/st/blob/code_v4_consolidation/tools/harry_porter.md#harry-porter-v3-to-v4-character-conversion-tool]repository of the script[/url].

There are only two things you as the scenario author will have to do once Harry Porter has finished running:
If you have characters with poses that are, by default, facing to the right (meaning their body is turned to the right-hand side of the image), you will have to let the game know about this deviation from the norm.
Either you flip your character images or, the simpler solution, you go into the "character.json" file for the affected character and add the following snippet:
[code]
    "poses": {
        "a": {
            "facing": "right"
        },
        "b": {
            "facing": "right"
        }
    },
[/code]

You only have to add poses that are facing the right-hand side of the image. Simply add the affected poses with the template above and you'll be good to go.

The other thing you have to do might be slightly more tedious, depending on how good you've been with managing character images so far. Since image sizes are now inferred from the actual image files themselves (instead of you having to manually enter them), we do not support characters with legs anymore. Well, we still do, but they will show up with their legs intact and reach out of the top of the screen because of that. As such, you will have to go through and pull a Katawa Shoujo and remove the legs from all characters that have them.

Of course you'll have to keep in mind that even if you start porting right now, you won't be able to properly test whether your port was successful until the actual release of v4. If you really absolutely *need* to try it out, you can download the source-code of the new scenario mode from the branch [url=https://stgit.ddns.net:1234/vncollab/st/-/archive/code_v4_consolidation/st-code_v4_consolidation.zip]code_v4_consolidation[/url], which you can then run with a copy of the Ren'Py engine if you add it as a project. Be aware that you'll have to set up the engine yourself and will be subjcet to major spoilers. You can find a guide on how to do this in the Getting Started topic since this is a similar setup to what we as the dev-team use. If you want some basic testing to be done once your initial conversion is finished, you can also talk to me directly, either via PM or on Discord, and I will test it for you and help you with the process.

To close this thing off, we'll leave you with a few "best practices" for custom characters in Scenario Mode:
- Character images should be in PNG or WebP format.
- While characters can work without their "character.json" being given, it is advisable to fill in at least the correct name and name color for a character.
- Characters should be prescaled as much as possible. If you have to set the scale outside of the range 0.8 to 1.2 you should consider rescaling your images beforehand.
- Optimise your images with software like [url=https://pnggauntlet.com]PngGauntlet[/url] (Windows), [url=https://imageoptim.com/mac]ImageOptim[/url] (macOS) or [url=https://trimage.org]Trimage[/url] (Linux / Unix) for filesize savings. Make sure you use lossless compression in all cases to avoid artifacts!
- If you use just a few characters from another scenario (less than 5), copy them into your scenario so that you don't depend on the other scenario.
- If you use many characters from another scenario (more than or equal to 5), use them directly without copying them. Make sure you notify your players of the fact that they will have to install a second scenario, preferably in big-bold letters right next to your main download link and provide a link to that scenario.
- If you want to extend an existing character, either from another scenario or from the base game, copy them into your scenario and modify them there. This ensures that modified characters of the same name don't conflict and that all scenarios and the base game display as they should.
- Use as little custom characters as possible. The cast we provide is already rather large and we generally pay attention to file size and RAM requirements. This is especially important because a large amount of sprites might lead to Out Of Memory issues when too many scenarios are installed. So please take care to keep your scenarios as lightweight as possible.

If you have any further questions regarding the new character format, don't hesitate to ask them over in the [url=https://tfgames.site/phpbb3/viewtopic.php?f=72&t=8846#p347156]Scenario Guide[/url] thread and we'll do our best to help you out. Please take notice of the fact that things are not set in stone yet and thus subject to change. However, we've almost finished implementation of this feature, so there are no big surprises to be expected.