The term CDL refers to the characteristics of a cabinet for a specific game.
Cabinet Asset structure
Cabinets contains two main components:
Cabinet Model: Consider a piece of wood furniture that is unpainted and has the shape and components of an arcade cabinet.
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 re-skin them. New versions of the game should include new models.
Starting at version 0.2 models can be included in the cabinet asset too.
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.
Note: You don’t need to be a programmer or a graphics designer to make new cabinets assets starting of a base model.
---name: xeviousyear: 1982author: curifcomments: is a vertically scrolling shooter arcade video game developed and published by Namco in 1982. It was released in Japan by Namco and in North America by Atari, Inc. Controlling the Solvalou starship, the player attacks Xevious forces before they destroy all of mankind. The Solvalou has two weapons at its disposal: a zapper to destroy flying craft, and a blaster to bomb ground installations and enemies. It runs on the Namco Galaga arcade system.rom: xevious.ziptimetoload: 18md5sum: fe6e9e3d5d1faaab2f53d97fed83c562enablesavestate: falsestatefile: state.nvspace: 1x1x2material: black
name: name of the cabinet, usually the same name of the ROM. if the ROM is dkong.zip, then the cabinet asset file name is dkong.zip too and the name of the cabinet is dkong. Please don’t confuse files, that usually happens because cabinet assets and ROMs have the same file name, but, by using this way, it’s easy to know witch cabinet asset is made for each ROM, just store those files in different folders.
timetoload: (optional) Time to load is the time that the engine wait after load the game. It tells MAME to load the game, wait N timetoload seconds, and then tells it to insert a coin. There isn’t any way to know when MAME finished the boot phase, then the only way is to wait. Obviously not all games take the same, and because of that we need to configure timetoload. To obtain a timetoload just counts the seconds that the boot phase take.
md5sum: MD5 can be used as a checksum to verify data integrity against unintentional corruption (Wikipedia). To verify if your ROM is the same that the one we tested, go to this page and get the MD5 of your ROM, compare it with the registered, must be the same.
enablesavestate: Enable it (true) if AGE of Joy should save the state after the timetoload period. This key is optional, defaults to false. 2
statefile: file name of the state file. This key is optional, defaults to state.nv. 2
material: (optional) a material to use for all parts of the cabinet. materials are explained below.
space: Short of Occupied Space. Space in units that the cabinet will fill in the Room: Cabinet space sizes
Optional keys:
author: cabinet author Nik name.
comments: any extra relevant information
The enablesavestate key
Warning
states isn’t working and was deprecated.
Each game has its own boot process, which is initiated when the arcade gallery owner powers on the cabinet. Bypassing the boot process is a desirable feature that allows the player to skip the boot process every time he or she wants to play.
To avoid this process, AGE of Joy saves the game’s state (memory, CPU states, etc.) after the ‘timetoload’ period of time has passed. The game will re-start at that point the next time it is run, skipping the boot load phase and arriving at the point where the game is ready to accept the first coin. It’s similar to how a computer goes and back from hibernation.
roms
You could create roms playlists to play a game and move to the next one if you want. This allow Cabinet Artist to create multi-rom cabinets.
Cycle through games with Left Trigger + Left thumb click while playing.
roms: - samsho.zip - samsho2.zip
The rom key is going to be ignored if you create a playlist.
Cabinet models reference
style: xevious
style: is the name of the Cabinet Model. The most common cabinets are bundled in the game and can be reused. Members of the AGE of Joy community frequently reuse cabinet models to create a new one.
model: a document to describe the cabinet model to use when the model is bundled in a cabinet asset (not inside the game). The model key and the style key are mutually exclusive and cannot exists in the same description.yaml file at the same time.
file: Is the file name of the model. These models files are in glb (gLTF) binary format. The cabinet asset must contain the file unless a style key exists.
style: part of the model document, refers to a previous uploaded cabinet asset model. In the example, the mslug.zip file cabinet asset must contain a NeoGeo.glb model. This key is optional, defaults to the actual model.
You can also add your preferred cores. Read the Cores documentation.
Attraction mode
Attraction mode in arcade machines refers to the visual and audio display that plays automatically when the machine is idle and no one is actively playing. It serves as a way to grab the attention of passersby and entice them to play the game.
Attraction videos
Every game runs it’s own introduction when nobody is playing, showing the game play or instructions. Because of the limited power of some devices, not all games can be emulated at the same time to display these screens. To solve this problem and to obtain the more accurate experience possible an introduction video is playing when the player is not in game mode (playing the game). These videos are typically obtained using RetroArch (by running the game and recording the introduction part), the result is a .mkv file that can be included in the cabinet asset.
video: optional, a document describing the video to play.
file: file name of the video, must be included in the cabinet asset.
invertx: flip the video by the x axis (optional).
inverty: flip the video by the y axis (optional).
max-player-distance: is the distance between the cabinet and the player in which the video plays. If the player is far away the video stops and the attraction audio start playing. v0.6 and sup.
In Age of Joy, attraction videos play near arcade cabinets when players are close and looking at the screen. It’s a clever way to save CPU resources while enhancing the gaming experience.
Attraction videos usually plays when the player is close to the arcade cabinet and looking to the screen direction. Age of Joy tries to save CPU using this method, because the device isn’t capable to play all the rooms attraction videos at the same time.
An audio clip could be configured to play when the player is not looking at screen.
Attraction audio clip
An audio clip could be played when the player is far away the cabinet or looking to other side. It is a way to get the same effect of the attraction video playing, without the CPU cost of decompress and play a video.
Attraction audios uses spatialization to create the effect of position in the 3d space.
parts: optional. A list of documents describing the parts of the model. If is missing, the engine will configure all the parts using the material key in the root of the document. Each part document describes the way the part is skinned: can be a material, a color or an art.
name: name of the part to be configured. Each part that is not described in the list is configured according the material key (root). Each part registered in ‘description.yaml’ must have a component in the cabinet model (the name of the object in Blender)
type: can be bezel, marquee, blocker or default. Optional key, defaults to default if missing.
(parts in blender)
type parts
Age of Joy reacts to the type key offering special characteristics and functions for each one.
default: For a common component, like the left wood.
bezel: to apply to a component that will show an image with transparency. Usually for a bezel.
marquee: to show images with background lights. Typically for the marquee, but some cabinets (such as xevious or tron) have more than one.
blocker: a component to limit the player movement on it. If you don’t add a blocker part Age of Joy will create one around the cabinet. The player cannot cross the blocker area. Read the Player Blockers page to understand how to use it.
Coloring parts
The RGB color to apply to the cabinet component.
Example:
color: r: 238 g: 232 b: 176 intensity: 1
color: the color document
r: red color component (integer 0-255)
g: green color component (integer 0-255)
b: blue color component (integer 0-255)
intensity: intensity multiplier, integer, can be negative to obtain darker variants of the color.
Applying a material to a part
A material is a pre-configured color, may be skinned (with textures) or not. They are included in the game.
Example:
- name: bordercrt material: plastic
material: the name of one included material in the game.
Materials included:
black: black wood cabinet
base: base material to modify (colors for example)
wood:
lightwood
darkwood
plastic
glass:
dirty glass: a dirty one.
clean glass: a clean reflective glass.
layer glass: allows transparency on pictures (like 1979 Space Invaders’ screen layer)
Normal maps
A normal is a small texture that contains information about the surface geometry of an object. They create the illusion of detailed surface geometry.
normal: wood
They are useful to simulate a surface at low cost, the other way, adding an art picture is more expensive (the system needs to load the picture from disk). Example: you can set a brown color to a part and the wood normal to simulate wood.
Included
wood
plastic
rubber
scratches
treadplate round
treadplate diamond
cloth
paint
scratches 2
corroed metal
”Art” parts
The Art document describes how the part is textured. The cabinet developer must provide images based on the requirements of each part.
Example:
art: file: left.png inverty: true invertx: true
art: the art document.
file: file name of the image used as a texture for the part. The file must be included in the cabinet asset.
The visible key allows Cabinet Artists to hide cabinet parts. Useful for example to set cabinets parts that acts like marks in the 3D space, the most usual use case is the player head position used to set the player in a specific position when inserts a coin (using AGEBasic). This is the started visibility, you can change it with the function CabPartsEnable(), read AGEBasic in cabinets.
Default: true
visible: false
Bezel Configuration
The bezel type allows the use of specialized shaders to create a bezel effect, simulating a glass overlay with a large decorative sticker.
There are several sub-type options available to customize the bezel behavior. Each sub-type uses alternate shaders, enabling different visual and performance characteristics:
No sub-type or sub-type = default:
Uses the classic bezel shader, which is the standard rendering option.
sub-type = simple:
Utilizes a new, highly optimized shader that handles the alpha channel much faster. In this mode, pixels are either fully transparent or fully opaque—no partial transparency. This shader is ideal for simple bezels and stickers where precise transparency is unnecessary. It reduces VRAM usage and improves performance, especially for textured areas of the cabinet (such as sides).
sub-type = dirty glass:
Combines a “dirty glass” effect with alpha transparency in a single rendering pass, eliminating the need to layer multiple shaders. This approach reduces draw calls and enhances performance. This shader also includes two new properties, glossiness and dirtiness, which can be adjusted to fine-tune the effect.
The marquee system simulates both the image and the lighting that illuminates it, providing flexibility to recreate the classic look of older arcade machines or a more modern feel with different light sources.
The Marquee in CDL represents not only the glass where the art image is displayed but also the lighting system inside the cabinet. This system can consist of one or two lamps or tubes, and you can also opt to have no illumination.
art: Specifies the image (left.png) to be displayed on the marquee, with options to invert the image vertically (inverty) or horizontally (invertx).
marquee > illumination-type: Defines the type of lighting used inside the marquee. Options include:
none: No illumination.
one-lamp: Single lamp.
two-lamps: Two lamps.
one-tube: Single fluorescent tube.
two-tubes: Two fluorescent tubes.
Any unrecognized value defaults to one-lamp.
color: Defines the color tint applied to the marquee texture (added in the v0.6),
marquee > color: Configures the color and brightness of the lamps inside the marquee.
For a vintage look (incandescent lamps from the 1980s), choose a warm, yellowish hue.
For a more modern appearance (fluorescent tubes), opt for a white color.
r, g, b values set the RGB color of the light, and intensity adjusts the brightness.
Properties
material-properties is a dictionary that configures the shader properties of a material applied to a part. The available properties depend on the specific material shader being used, but the most common ones are:
metallic: Ranges from 0 to 1.
color: Red, green, and blue values, each ranging from 0 to 1.
smoothness: Ranges from 0 to 1.
emission-color: Red, green, and blue values, each ranging from 0 to 1.
Other properties from Unity’s Standard Shader may be supported, depending on the material being used.
Combinations
Starting on v0.5 it is possible to combine materials with colors, transparency, etc. Some keys works better with specific materials, for example, layer glass material with transparency.
Example 1: a glass with a colored layer and a bezel on top of it.
Typically, cabinet parts represent decorative or static objects that the player does not interact with. However, in certain cases, a part may need to respond to its environment—such as gravity or player interactions. In those situations, the part should be marked as physical.
Here’s a description of the YAML specification for configuring audio in the cabinet parts:
YAML Audio Configuration Specification
audio: Defines the audio configuration for a specific cabinet part. This section includes various settings related to audio playback, volume, looping, and 3D sound effects.
file: Specifies the name of the audio file that should be assigned to the cabinet part. The file can be in WAV, MP3, or OGG format and must be distributed in the Cabinet pack.
Example:
file: "gong.mp3"
This assigns the “gong.mp3” file to the part.
volume: Sets the volume level for the audio playback. The value should be a float between 0.0 (muted) and 1.0 (full volume).
Example:
volume: 0.5
This sets the audio volume to 50%.
loop: Defines whether the audio should loop continuously. The value can be true (looping enabled) or false (looping disabled).
Example:
loop: false
This disables looping for the audio.
distance: Specifies the minimum and maximum distances for 3D audio effects, which determine how the audio is perceived spatially within the game environment.
min: Sets the minimum distance at which the audio starts being audible.
Example:
min: 1
This sets the minimum distance to 1 unit.
max: Sets the maximum distance at which the audio is fully attenuated or fades out completely.
Example:
max: 5
This sets the maximum distance to 5 units.
Complete Example
Here’s how a complete YAML configuration for a cabinet part might look:
This configuration assigns the “gong.mp3” audio file to the cabinet part, sets the volume to 50%, disables looping, and applies 3D sound settings with a minimum distance of 1 unit and a maximum distance of 5 units.
You can play, pause or change properties using AGEBasic.
The most used screen for cabinets was the 19i. AGE of Joy comes with that model included in the game, other models could be included in the future.
The crt document comes in two parts: the root for a tube element configuration (orientation, geometry, etc) and the screen to configure how
the game and video looks when play.
shader: Shaders in screen are utilized in Age of Joy to mimic the effects seen on old CRTs found in arcade galleries, which often operated for extended periods, sometimes 24/7. These CRTs commonly develop defects over time, which can be observed during gameplay.
damage: how damaged is the CRT. Usually high, medium and low
invertx: flip the game image by the x axis (optional).
inverty: flip the game image by the y axis (optional).
properties: a list of shader’s properties. You can change the shader’s behavior changing these properties (hard to do it and you need to know every property effect on each different shader. Is not recommended). Version >= 0.5. See the Materials example below.
The default shader is crt.
CRT shader
Available after the version 0.5.0, This shader carefully recreates the look of old CRT monitors from that time period. You’ll notice simulated dirt on the screen and realistic scanlines when you get close to the monitor, giving you an authentic retro feel.
screen: shader: crt damage: low
Note
This shader heavily relies on the GPU, but it has been replaced by a more GPU-friendly version called crtlod for attraction videos. Joust select crt and it will replaced automatically for videos.
CRT LOD shader
Like CRT but GPU-friendly.
CRT LOD is forced for attraction videos when CRT Shader is selected.
rotation: to configure the rotation optional sub-document. Its possible to configure a rotation for each axis. The value is in degrees, the example rotates the screen -90 degrees in x axis. Optional, all axis optional too, defaults to 0.
scalepercentage: increase or decrease the size of the element by a percentage. Optional, default to 100%. Integer, can be negative.
ratio: to change the scale (between 0 and 1 - 1=100%)
Coin slot configuration
The place where to drop coins to start games.
The coin slot position is configured in the model.
coinslot: coin slot model to apply: coin-slot-double or coin-slot-small
coinslotgeometry: the same geometry sub-document than in CRT.
Insert coin
Set to true to not start the game when you insert the first coin. Useful in games that you want to enjoy the start of the game (presentation activities).
insert-coin-on-startup: false
Controllers
Some games needs a specific controller configuration to be playable.
Available starting at 0.4 version.
A light gun is a type of input device used to interact with video games. It is designed to resemble a firearm and is used to target and shoot objects or enemies on the screen. Light guns were particularly popular during the 1970s, 1980s, and 1990s in arcade gaming.
active: to activate the light gun. (true/false). Defaults to false.
device: device id in the core if you know it, 260 is GunCon on swanstation. Omit it by default.
model: a .glb file with a model that represents the light gun. Age of Joy will change the right controller model by the model after load it. Remember: the load file operation is CPU intensive (even in async mode), you should use low poly models with little or not texture in order to not freeze the game for a long period of time. The model file must to be present in the Cabinet Asset.
The model metrics is in meters, Age of Joy makes none adjustment to the size or rotation. But if it is inverted you can use the invert-pointer property.
If you download a model from internet, don’t forget to give the credit to the author. You can write a file with the license in the Cabinet Asset.
gun: about the gun representation in VR
invert-pointer: some meshes are inverted (they shoot to the opposite part of the gun)
adjust-sight: allows you to adjust the point where the “bullet” will hit the screen in relation to the light gun. This property allows cabinets developers to adjust the sight point in the screen to the gun model. Start testing with a little value like 2 or 3.
horizontal: measured in cm (centimeters), moves the gun up or down (without noticeable real movement of the gun) to adjust the shoot. Can be negative to move the sight down.
vertical: same as horizontal. A negative value moves to sight to the left.
debug:
active: to activate a mark where the gun hit the screen. Activate only when you are working in the cabinet development.
crt: to adapt the light gun behavior’s to the CRT measurement. Don’t touch it, is loaded by default, unless the CRT changes.
mesh-factor-scale-x: Screen mesh scale factor to adjust in width. 0.01 by default (deprecated in version >=0.5)
mesh-factor-scale-y: idem previous. 0.01 by default (deprecated in version >=0.5)
border-size-x: CRT border size left to exclude. 1.5 by default (deprecated in version >=0.5)
border-size-y: idem previous. 1.0 by default (deprecated in version >=0.5)
invertx: Invert to negative/positive the x point where the gun shoot the screen, true by default.
Available on version >= 0.5 RC4
It’s important to note that while MAME itself is a legal project, the use of ROMs may have legal implications. Distributing or downloading copyrighted ROMs or related files without the proper ownership rights is generally illegal. It is recommended to only use ROMs and files for which you have the appropriate permissions or obtain them from legal sources, such as original arcade machine owners or authorized distributors.
In addition to the art files, various other files such as configuration files, RAM files, and more are integral components of the MAME engine (or any other core). At times, these files are essential for playing a game or complementing its functionality. Sound samples serve as a prime example; while the game may run, certain sounds may be absent.
To streamline the installation process for players, Cabinet Artists could consider including these files in the cabinet asset zip file. Furthermore, they could describe in CDL the method by which Age of Joy will distribute the files, enabling MAME to locate and utilize them seamlessly.
It is also used to distribute other files types like music for the Jukebox.
File Type
Description
config
Configuration files for MAME emulator settings
disk-image
Disk images
sample
Sample files containing audio for certain games
nvram
NVRAM files storing non-volatile memory data
music
music clips for the jukebox.
Describes the file distribution in the description.yaml file
mame-files: This indicates a list of files that MAME utilizes.
file: Specifies the name of each file (must be in the zip file).
type: Indicates the type of file (e.g., disk-image, sample, config, nvram).
By including such information in the description.yaml file, it provides clear instructions for Age of Joy on where each file is located and its corresponding type, facilitating efficient file management and distribution.
AGE Basic
You can run AGEBasic programs designed for a specific cabinet. Age of Joy has the ability to execute programs in response to predefined events, like when a user inserts a coin for the first time.
AGEBasic programs must be included in the Cabinet Asset.
agebasic: active: true debug: true after-insert-coin: start_game.bas # Run this program when a coin is inserted after-load: initialize.bas # Run this program on cabinet startup after-leave: save_data.bas # Run this program when the player leaves system-skin: c64 variables: - name: myvar type: string value: This is a test events: - event: on-always program: move.bas ```This document details the `agebasic` configuration section within your arcade cabinet, controlling AGEBasic program behavior.### General Settings:* **`active` (boolean):** * **Enabled (true):** AGEBasic programs run normally (default). * **Disabled (false):** All programs are inactive, useful for troubleshooting.* **`debug` (boolean):** * **Enabled (true):** Creates debug files for each executed program. * **Disabled (false):** No debug files generated.### Program Execution Triggers* **`after-insert-coin` (string):** * Filename of the program that runs **once** when a coin is inserted to start the game.* **`after-load` (string):** * Filename of the program that runs **once** after the cabinet fully loads (startup).* **`after-leave` (string):** * Filename of the program that runs **once** when the player leaves the game.* events: read the [[AGEBasic event system]] for a full description.### System skinThe `system-skin` key configures the look & feel of the AGEBasic screen to mimic retro-computers.At the moment these are the options:- `zx`: Sinclair look and feel- `cpc`: Amstrad- `c64`: Commodore 64**Variables:*** **`variables` (list of objects):** * Defines variables accessible to all AGEBasic programs. * Each object specifies: * **`name` (string):** Unique variable name following [[AGEBasic programing#variables|Variables]] conventions. * **`type` (string):** Data type (`string` or `number`). * **`value` (string):** Initial value (converted to specified type).**Example Configuration:**Read this document to fully understand how AGEBasic programs works in the cabinet's environment: [[AGEBasic in cabinets]].## DebugIt easy to fail the task of writing a `yaml` file, It's common to introduce syntax or semantic error. [[Cabinet Artist]]s should analyze debug information about the cabinet they are making.### Activate the debug modeJust set to `true` the debug-mode key in the `description.yaml`:```yaml title="description.yaml"debug-mode: true
