Upgrade Guide

Backwards Compatibility

To help ease the transition to new major versions, limited backwards compatibility has been added. For example, if your configuration file has a 5.x schema like this at the top:

# yaml-language-server: $schema=https://gcpw.art/tvs/schemas/5.11.0.json

Your config file will be loaded in compatibility mode, which will translate your config file on-the-fly to work around breaking changes. Some things like removed / moved engines (basic-text and video-game) will not load but channels that can be loaded with modifications will load.

Compatibility mode is not meant to be a long-term solution; when you’re ready to take advantage of new features and improvements, you can follow the steps below to update to new schemas.

Upgrade Guide 5.x -> 6.0

You can use our automated upgrade utility to help upgrade your config file. Visit /upgrade-utility in TVS 6.x or later or use the hosted version.

1. Change the schema line to the 6.0 schema:

   # yaml-language-server: $schema=https://gcpw.art/tvs/schemas/6.0.0.json

2. Replace any basic-text engine usage with character-generator. I’ve prepared a template that looks the same as basic-text’s defaults that you can drop in:

   - number: 1
     name: Basic Text backwards compatibility
     abbr: TEXT
     character-generator:
       src: placeholders/config-examples/bulletins/basic-text.json
       lines:
         line:
           - text: First line of text # put your text here
           - text: Second line of text

3. Replace any video-game engine usage with the new iframe version. You can self-host it or use the hosted version:

   - number: -1
     iframe:
       src: http://gcpw.art/tvs/engines/video-game # replace with your own server if self-hosting
       options:
         game: flappybird.nes # Required. The game library by default is from `retrobrews.github.io`. You can specify a game from there directly. Set to false to use a core that doesn't require a game.
         core: fceumm # Required. The system to emulate.

4. Change usage of mix from the old to new syntax:

   • Use a list rather than a and b
   • mixMode: becomes _mix.mode
   • opacity: becomes _mix.opacity

   Old syntax:

   - number: 133
     name: Mix Layout
     mix:
       a:
         opacity: 0.6
         image: placeholders/example-program.webp
       b:
         mixMode: difference
         generator: test-pattern

   New syntax:

   - number: 133
   name: Mix Layout
   mix:
       - image: placeholders/example-program.webp
         _mix:
           opacity: 0.6
       - generator: test-pattern
         _mix:
           mode: difference

5. Change usage of v-split and h-split from the old to new syntax:

   Old syntax:

   - number: 139
   name: V-Split
     v-split:
       a:
         color: red
       b:
         color: blue

   New syntax:

   - number: 139
     name: V-Split
     v-split:
       - color: red
       - color: blue

   splitPercentage can continue to be used but only if you have two components. The new equivalent is _split.weight:

   - number: 139
   name: V-Split
     v-split:
       - color: red
       - color: blue
         _split:
           weight: 2 # This component will take up two units of weight compared to the others. The default is to distribute each component equally (1 weight per component)
       - color: green

6. Move channel title and description to info section

   Anywhere where you have a channel with title and description attributes, move these to the info section and replace description with summary.

   Old syntax:

   - number: 2
     name: Welcome
     abbr: WELCOME
     title: Thanks for testing Television Simulator!
     description: Welcome to TVS 6.0!

   New syntax:

   - number: 2
     name: Welcome
     abbr: WELCOME
     info:
       title: Thanks for testing Television Simulator!
       summary: Welcome to TVS 6.0!