How the cabinet building system works

Warning: tech talk. Read this if you want to create your own cabinets, if not, just download the cabinets assets packs.

Cabinets have two parts:

• Cabinet Model: Consider a piece of wood furniture that is unpainted and has the shape and components of an arcade cabinet.
• Cabinet assets: is a zip file that contains the side art stickers, bezels, marquees, and so on, as well as a description file that describes how to paint, how to place the stickers, marquee color light, tv (crt) position, the video to play on the screen when nobody is playing, etc.

The models of the cabinets, such as Galaga and Xevious, are included in the game, developed by an graphic artist, in a way that its design allows you to reskin them. New versions of the game should include new models. ! Without any special knowledge, it is possible to reuse a cabinet model, personalize it, zip the files, and copy it to the headset. Because all cabinets are made in this manner, the game does not include any cabinets assets bundled on it; however, you can create your own or download them starting with a base design. In fact, you can use a “galaga” design and change the side art, bezel, marquee, and so on. And then make a new one.

Obviously, you can download all the cabinets that you want because their are distributed as game assets

Note: You don’t need to be a programmer or a graphics designer to make new cabinets assets starting of a base model.

Creating new cabinets

Creating new cabinets is a trial-and-error process. There is a special room in the game called the Workshop where you can test your own cabinets.

You can upload the cabinet you’re working on as many times as you want to the workshop. When you are satisfied with the outcome, you can place the cabinet in the game. The cabinet will be automatically installed in a room by the game.

The best way to make a new cabinet asset for a game is to copy an existing one, decompressing galaga.zip for example, and replace each file for the one that correspond to the game. It’s important to use the same characteristic for each file, for example the width and eight for the side art graphics and the same rotation.

The special file description.yaml describes the parts of the cabinet.

Detailed instructions at the end of this post.

The Cabinet Description Language

This is an example of the Cabinet Description Language (CDL) in the description.yaml in galaxian.zip, a text file describing a cabinet in a computer language known as YAML (this is the simplest way to communicate with a computer system).

name: galaxian
rom: galaxian.zip
crt:
  type: 19i
  orientation: vertical
  screen:
    damage: low
    invertx: false
    inverty: true
style: galaga
material: black
year: 1979
coinslot: coin-slot-double
timetoload: 5
video:
  file: video.mkv
parts:
  - name: left
    art: 
      file: left.png
  - name: right
    art: 
      file: right.png
  - name: joystick
    art: 
      file: joystick.png
      inverty: true
  - name: joystick-down
    art: 
      file: joystick-down.png
  - name: front
    art: 
      file: front.png
  - name: bezel
    type: bezel
    art:
      file: bezel.png
  - name: marquee
    type: marquee
    art:
      file: marquee.png
    color:
      r: 238
      g: 232
      b: 176
      intensity: -2

You can use CDL to describe all of the design details of each part of a cabinet model simply by using a text editor on your computer.

Once you understand the language, it’s easy to develop new cabinets.

A detailed description in the documentation page

Testing cabinets assets

Once your cabinet is complete, you can begin testing it. Normally, it should not work; some adjustments may be required, this happens a lot.

There are a special room the workshop where you can see and test the new cabinet. To deploy the cabinet there name it test.zip and copy to the /sdcard/Android/data/com.curif.AgeOfJoy/cabinets folder (as usual, but with that special name). AGE of Joy will reload the cabinet immediately (this only happens in the workshop with that cabinet, but not in the rest of the rooms). Repeat the process until you are confident with the result.

At the end, rename the final cabinet with a unique name, two different cabinets can’t have the same name. As a rule, I use the name of the ROM as the name of the cabinet, so your cabinet will be unique in the gallery and in the cabinet assets universe too.

You can, of course, publish your cabinet.

Step by step

This is a step by step guide to craft a new cabinet for a ROM.

In this example, we will use the Galaga cabinet to craft a new Galaxian cabinet for the Galaxian ROM

1- Check the ROM

In theory any ROM that works in Libretro MAME 2003+ should work, BUT there are some issues that must be managed in AGE of Joy to use some ROMs. One of them, for example, is the image format because not all ROMS uses the same image format, and if you ROM uses one that is not supported, then the game don’t run or may show weird colors, lost frames, etc.

If you can’t find a cabinet for your rom you should create a new one.

2- Craft a new cabinet for testing purposes

This method uses a previously saved model (bundled in the game) and reuse it. Starting with a cabinet asset and modifying it. A good start point is the Galaga cabinet, in this example we will modify the cabinet and we will create a new one.

2.1 Decompress an existing cabinet asset in your PC

• Create a new folder in your PC with the name of the cabinet you want to create, for example galaxian
• Copy a cabinet asset to your PC, for example galaga.zip and extract all the files to your new folder galaxian. Warning: its easy to confuse a cabinet asset with a ROM, usually the have the same file name.
• Now you should have a lot of files, some pngs, a mkv, and the most important description.yaml in the recently created galaxian folder

2.2 change the description file

• With a text editor open the description.yaml file
• Edit the cabinet name and rom filename:

Previously:

name: galaga
rom: galaga.zip

After your changes:

name: galaxian
rom: galaxian.zip

• Save the file.

2.3 Compress to a new zip file

Depending on you operative system there are diferent ways to compress files. This example is for ubuntu.

• Select all files in the galaxian folder
• Mouse right button opens a menu, then Compress...
• Create a new zip file with the name test.zip in any place in your disk.

The test.zip file is a special cabinet asset name for testing purposses only.

3- Test the cabinet

To test the cabinet you need to copy the test.zip cabinet asset to the headset, using Sidequest for example. Remember: test.zip is for testing purposes, we should rename the zip file later after the testing phase.

• Follow this instructions in order to copy the test.zip file to the /sdcard/Android/data/com.curif.AgeOfJoy/cabinets folder.
• Copy the ROM file to /sdcard/Android/data/com.curif.AgeOfJoy/downloads, in this example our ROM file name is ‘galaxian.zip’.
• Go to the workshop in the game (the door at your left with the wet floor sign in front), if all is ok the new cabinet should spawn in the middle of the Room. If not, or shows something weird like a mutant cabinet, or one cabinet inside the other, then something failed.
• Walk to the cabinet, insert a coin and look what is happening.

If the game didn’t start or the cabinet didn’t spawn correctly, check the description.yaml file in search of errors. But if you didn’t find any issue, then probably you ROM is not compatible. Ask for help in forums and GitHub.

If you find the issue (may be a typo) repeat all from the step 2.3. The corrected cabinet will replace the actual without need to restart AGE of Joy.

4- Deploy the new cabinet

If your game is running without any noticeable issue, then you can deploy the new cabinet:

• Rename the file in your PC from test.zip to a file name that represents the game in the cabinet, in our example should be galaxian.zip
• Copy the file to the /sdcard/Android/data/com.curif.AgeOfJoy/cabinets folder.
• Start AGE of Joy again, the program will find the new cabinet and move it to the cabinets database (the /sdcard/Android/data/com.curif.AgeOfJoy/cabinetsdb folder). Don’t touch that folder is for internal uses only. The game will delete the original zip file from /sdcard/Android/data/com.curif.AgeOfJoy/cabinets
• After register the new cabinet, it will be deployed in an empty slot inside a Room in the game, replacing an “out of order” cabinet.

Enjoy your new cabinet!