This tool lets you edit and create your own downloadable content for Sonic Adventure on the Dreamcast. The DLCs created with this tool can be played on real Dreamcast hardware without hacking the base game.

Table of Contents

• DLC VMS File Structure
• Using the Editor
  • Main Tab
  • Messages Tab
  • Textures Tab
  • Model Tab
  • Sound Tab
  • Importing and Exporting
• Additional Notes
• Troubleshooting
• Credits
• SA1 DLC File Format

---

DLC VMS File Structure

A VMS file with SA1 DLC contains the following sections:

1. A general header common for all VMS files;
2. An object layout (item table) to tell which objects to load in which level as well as flags to restrict the DLC to specific characters or versions of the game;
3. A string table containing messages in different languages (up to 16 per language);
4. A PVM file containing textures;
5. (Optional) An MLT file containing sequenced sound effects or music;
6. A PRS-compressed binary containing a model in the Ninja Basic format.

Using the Editor

The easiest way to get started is to open the VMS file of any official DLC or Tikal's Challenge DLC, change it the way you want and save it as a new VMS file.

Main Tab

Here you can change header information, set DLC regional and character locks and access the item table.

Icon

The icon must be a 32x32 bitmap. It's recommended to prepare a 16-color image for the icon. If the icon has more colors, it will be converted to a 16-color image with quality loss.

About the DLC ID field

For the game to recognize the DLC, its filename on the memory card should be SONICADV_XXX, where XXX is a 3-digit number unique to each DLC. IDs 0-199 are reserved for Japan-only DLCs. If you use a number lower than 200 for the ID, the game will only display messages in Japanese.

Apart from the filename, DLC ID can also be stored in the VMS file itself. If the DLC sets up a challenge with a timer, the DLC ID is saved in the upload data produced by the game. The DLC ID field in this tool sets both the filename and the field in the file.

Regional locks

Regional locks have been tested on the following versions of the game:

• JP: Original Japanese release (1.007)
• US: Original US release (1.004) and All Stars re-release (1.005)
• EU: European release (1.003)
• INT: Second Japanese release known as "Sonic Adventure International" (1.003)

The behavior of the locks is as follows:

• Disabled and All Regions: works on all versions of the game
• Japan: JP, INT
• Exclude Europe: All versions except EU
• Europe Only: EU only

Object Editor

This editor lets you change the item table.

Object Flags

Solid - Enable collision.

Play Sound - Play a sound when the object is triggered. The sounds are restricted to currently loaded soundbanks which depend on where you are in the game. You can add a custom soundbank with sound effects or sequenced music via an MLT file. You can also play ADX music from the disc.

Show Message - Show a message when the object is triggered.

Collision Only - Disable all interactive elements and use the object as invisible collision.

Change Level - Teleport the character to a different level when the object is triggered.

Collectible - Make the object collectible. You can have up to 255 collectible objects.

Timer - Use the object to count the time and keep track of how many items have been collected. The timer works everywhere and does not reset if you go to another area, including different Acts of a stage, a different Action Stage or a different Adventure Field.

Challenge Start - Use the object to start the timer.

Notes and Tips

• You can use SALVL to get coordinates and rotation for your objects. Use any SET file or Sonic's start position as a placeholder. Alternatively, you could use the Debug Mode mod to retrieve the player's coordinates ingame and use them for your objects.
• An object cannot have both Play Sound and Change Level flags at the same time.
• The Texture field sets texture ID on the sprite or the first material of the model.
• For Timer objects, the ID/Time/Total field stores the number of objects to collect.
• For Challenge Start objects, the same field stores the time limit. The format is the number of seconds divided by 10, e.g. 60 is 10 minutes.
• For Change Level objects, the Warp to: Level field stores the level ID and the Warp to: Act field stores the act ID.
• For Play Sound objects, the Bank field stores the soundbank ID and the ID field stores the sound ID in the soundbank. Bank 8 is the DLC soundbank, 15 is ADX music.
• You can stop the stage's regular ADX music by playing bank 15 sound 110.

Soundbank IDs

The game uses the following soundbank IDs:

• 0: Common sounds (COMMON_BANK00 in SADX)
• 1: Level-specific object sounds (BANK01 files in SADX)
• 2: Common object sounds (check_sheet_bank02 in SADX)
• 3: Character sounds (BANK03 files in SADX)
• 4: Level-specific enemy sounds (BANK04 files in SADX)
• 5: Level-specific background noises (BANK05 files in SADX)
• 6: Character voice clips and cutscene sounds (BANK06 and E_ banks in SADX)
• 7: Chao-related music in SA1's ALIFE.MLT (does not exist in SADX)
• 8: Extra sounds and music in SA1 DLCs (does not exist in SADX)
• 15: Music and voices

There is a list of sound effect IDs for SADX, which is the same as SA1 for the most part.

Messages Tab

Text strings must be 64 characters long or less. Japanese strings must be 32 characters or less. Use TAB (actual tabulation) for text centering.

Textures Tab

The tool can import PVM files created with Texture Editor or ArchiveTool.

• To save space, use as few textures as possible and compress them using the VQ4 PVR format. You can save textures in this format using the PVR plugin for Photoshop.
• You can also squish rectangular textures into squares for use with rectangular banners. Use the Rectangle checkbox to preview them in stretched mode.

Model Tab

The DLC can store a single Ninja Basic model. You can add a model in SAModel's .sa1mdl format using the Load... button, or import a model from another DLC's extracted data (PRS or BIN file) using the Import Binary... button. The tool manages model data automatically. If you use a model in .sa1mdl format, you don't need to create a PRS file.

You can also export the model in .sa1mdl format using the Save... button or export binary model data as BIN or PRS using the Export Binary button.

• To save space, make your model as low poly as possible. Reduce the number of materials, vertices, meshsets etc. You can see the amount of data occupied by the model at the bottom of the Model tab.

Sound Tab

The tool can import and export Dreamcast Multi-Unit (MLT) files.

• The soundbank in the MLT file is loaded as Bank 8 in the game.
• At the moment SA Tools cannot edit MLT files, although you can extract some information from them using the MLTExtract command line tool on the SA Tools Research repo.

Import and Export

The Export option in the File menu lets you export the VMS file as a folder that can be loaded by the Dreamcast DLC mod in the PC version of SADX. The Import option allows to load exported data back into the editor.

When you export DLC data, the model is extracted in the SA1MDL format supported by SAMDL. Other sections are converted to a single INI file (metadata), which are explained below.

The metadata INI file contains things like the name of the DLC, the messages displayed when you touch objects, and the item table. Although this is no longer necessary, you can edit this data manually in a text editor. Here's an example of an item with comments:

[Item 0] // Item index, increases for every next item.
Level=26 // Internal ID of the level where the object will be loaded. 1-10 are Action Stages, 26 is Station Square etc.
Act=3 // Act ID where the object will be loaded.
ScaleX=10 // Scale of the model/sprite multiplied by 10, e.g. 10 means the object will not be scaled.
ScaleY=10
ScaleZ=10
ObjectType=TYPE_MODEL // Kind of object. Can be TYPE_MODEL (3D model), TYPE_SPRITE (flat model), TYPE_INVISIBLE (no geometry).
Flags=FLAG_MESSAGE, FLAG_WARP // Object flags.
MessageID=3 // ID of text string to display when you touch the object.
CollectibleID=1 // IDs for collectible objects. Each collectible needs to have a different ID that ranges from 1 to the total number of objects (up to 255).
TriggerRadius=20 // Distance required to trigger the object's action.
TextureID=1 // Force the model's material to a specific texture ID, useful for billboards but can work with 3D models too.
WarpLevelOrSoundbank=35 // Level ID to warp to or soundbank ID to play the sound when the object is triggered.
WarpActOrSoundID=2 // Act ID to warp to or sound ID to play when the object is triggered.
RotSpeedX=0 // Rotation speed.
RotSpeedY=10
RotSpeedZ=0
RotationX=49152 // Object rotation.
RotationY=4000
RotationZ=0
X=698 // Object position.
Y=0
Z=1600

Additional Notes

• Sound data (MLT) is not compatible with the PC version.
• At the moment you have to replace an existing DLC in the mod to load your DLC in the PC version.
• For editing message strings manually, use \n for newlines and TAB (actual tabulation) for text centering.

Troubleshooting

If the browser or the emulator cannot import your DLC file, check the following:

1. Make sure the filename in the VMI file matches the VMS filename.
2. Make sure Resource Name in the VMI is 8 characters or less.

If the file is imported successfully but the game doesn't load the DLC, check the following:

1. The filename on the VMU must be SONICADV_XXX, where XXX is a 3-digit number. For example, a file named SONICADV_512 will be detected by the game.
2. Make sure you aren't uploading an unencrypted file to the VMU. Encrypt VMS files in the Edit menu must be checked before you save the file.
3. Check region and character locks.

If the result file is not created on the VMU upon completing the challenge, make sure your Dreamcast has the browser settings configured.

Credits

Sappharad: providing C# code to decrypt VMS files and cracking the DLC checksum

Darksecond: original Perl code to decrypt VMS files

SA1 DLC File Format

For nerds here's an overview of SA1 DLC structures:

 * VMU HEADER
 * OFFSET	SIZE	TYPE		DESCRIPTION
 * 0		16		string		DLC title
 * 10		32		string		DLC description
 * 30		16		string		Application title
 * 40		2		ushort		Number of icons
 * 42		2		ushort		Animation speed
 * 44		2		ushort		Eyecatch type (unused)
 * 46		2		ushort		CRC (unused)
 * 48		4		uint32		Size without the header
 * 4C		20		null		Reserved
 * 60		32		ushort		Icon palette, 16 colors
 * 80		512		byte		Icon graphics
 * 
 * SECTIONS HEADER (SIZE 64 BYTES) 
 * 280		4		uint32		Pointer to item layout table
 * 284		4		uint32		Item count
 * 288		4		uint32		Pointer to string table
 * 28C		4		uint32		String item count
 * 290		4		uint32		Pointer to PVM
 * 294		4		uint32		Number of PVMs (always 1)
 * 298		4		uint32		Number of textures in the PVM
 * 29C		4		uint32		Pointer to MLT
 * 2A0		4		uint32		Number of MLTs (either 0 or 1)
 * 2A4		4		uint32		Pointer to PRS
 * 2A8		4		uint32		Number of PRSes (always 1)
 * 2AC		4		uint32		Checksum
 * 2B0		16		null		Unused
 * 
 * ITEM LAYOUT TABLE HEADER (SIZE 12 BYTES)
 * 2C0		4		uint32		DLC ID (e.g. 504 in SONICADV_504)
 * 2C4		1		byte		Enable Sonic / Enable Tails
 * 2C5		1		byte		Enable Knuckles / Enable Gamma
 * 2C6		1		byte		Enable Amy / Enable Big
 * 2C7		1		byte		Unknown, probably unused
 * 2C8		4		uint32		Regional lock
 *
 * ITEM LAYOUT TABLE (ARRAY BEGINS AT 0x2CC, ITEM SIZE 30 BYTES)
 *  0		1		uint8		Level ID
 *  1		1		uint8		Act ID
 *  2		1		uint8		Scale X multiplied by 10
 *  3		1		uint8		Scale Y multiplied by 10
 *  4		1		uint8		Scale Z multiplied by 10
 *  5		1		uint8		Rotation speed X
 *  6		1		uint8		Rotation speed Y
 *  7		1		uint8		Rotation speed Z
 *  8		1		sint8		Item type (0: model, -128: sprite, -1: invisible)
 *  9		1		uint8		Texture ID
 *  A		2		ushort		Flags
 *  C		1		uint8		Object ID used for collectible items or the number of objects to collect
 *  D		1		byte		Unknown
 *  E		1		uint8		Message ID to show when touching the object
 *  F		1		uint8		Trigger distance
 *  10		1		uint8		Level ID to warp or soundbank ID (8 for MLT, 15 for ADX music)
 *  11		1		uint8		Act ID to warp to or sound/music ID to play when touching the object
 *  12		2		ushort		Rotation X
 *  14		2		ushort		Rotation Y
 *  16		2		ushort		Rotation Z
 *  18		2		short		Position X
 *  1A		2		short		Position Y
 *  1C		2		short		Position Z
 *
 * DLC OBJECT FLAGS
 * BIT_0	Unknown
 * BIT_4	Unknown
 * BIT_8	Solid
 * BIT_9	Play sound
 * BIT_10	Show message
 * BIT_11	Hide object and disable everything except collision
 * BIT_12	Warp
 * BIT_13	Collectible item
 * BIT_14	Timer item
 * BIT_15	Starts the challenge
 *
 * REGIONAL LOCK BITS
 *	-1	Disable regional lock
 *	1	Japan
 *	3	US
 *	4	Europe
 *	7	All regions