SpaghettiKart/docs/mods-toml.md

mods.toml File Structure

The mods.toml file is a metadata file required for all mods and resource packs in SpaghettiKart. It uses the TOML format and defines important information about your mod, including its name, version, and dependencies.

Location

The mods.toml file must be placed at the root of your mod archive (.o2r, .zip) or folder.

MyMod/
├── mods.toml          <- Required at root level
├── textures/
│   └── ...
└── ...

Basic Structure

Here's a minimal mods.toml file:

[mod]
name = "my-awesome-mod"
version = "1.0.0"

Complete Structure

Here's a complete example with all supported fields:

[mod]
name = "my-awesome-mod"
version = "1.0.0"

[dependencies]
spaghettikart-assets = "=1.0.0-alpha1"
another-mod = ">=2.0.0"

Fields Reference

[mod] Section

Field	Type	Required	Description
name	String	Yes	Unique identifier for your mod. Use lowercase letters, numbers, and hyphens.
version	String	Yes	Version of your mod following Semantic Versioning (e.g., 1.0.0, 1.0.0-alpha1).

[dependencies] Section

The [dependencies] section is optional and allows you to specify other mods that your mod requires.

Each dependency is defined as:

[dependencies]
mod-name = "version-requirement"

Version Requirements

Version requirements follow semantic versioning ranges:

Format	Description	Example
1.0.0	Exact version	Only version 1.0.0
>=1.0.0	Greater than or equal	Version 1.0.0 or higher
>=1.0.0 <2.0.0	Range	Between 1.0.0 (inclusive) and 2.0.0 (exclusive)
>=1.0.0-alpha1	With prerelease	Version 1.0.0-alpha1 or higher
see Semantic Versioning for more details.

Core Dependencies

SpaghettiKart defines three core packages that are always available:

• mk64-assets - The base game resources (version 1.0.0-alpha1) (mk64.o2r)
• extended-assets - SpaghettiKart additional assets (version 1.0.0-alpha1) (spaghetti.o2r)
• spaghettikart-core - SpaghettiKart core engine (For verifying that mods support your game version)

If your mod depends on touching base game assets or SpaghettiKart assets, you should declare a dependency on these packages. For example:

[dependencies]
mk64-assets = "=1.0.0-alpha1"

Validation

When SpaghettiKart loads mods, it performs the following validations:

1. Missing mods.toml: A warning is shown if the file is missing. The mod may still load but is considered incompatible.
2. Cyclic dependencies: If mod A depends on mod B and mod B depends on mod A, an error is shown.
3. Missing dependencies: If a required dependency is not found or has an incompatible version, an error is shown.

Load Order

Mods are automatically sorted based on their dependencies:

• Mods without dependencies are loaded first
• Mods are loaded after their dependencies

Best Practices

1. Follow semantic versioning: Use proper version numbers (MAJOR.MINOR.PATCH)
2. Specify minimal dependencies: Only declare dependencies you actually need
3. Use version ranges: Prefer =1.0.0 because assets may change between versions

Migration Script Support

When using the migration script (migrations.py), a mods.toml file can be automatically generated for your migrated mod. See Migration Guide for details.

See Also

• Modding Guide - General modding information
• Migration Guide - How to migrate existing mods
• Texture Pack Guide - Creating texture packs