CML Mod Format

File Hierarchy (Simple Explanation)

Mod Directory + description.txt + version.txt + compat.txt > Merge > Normal SM File Hierarchy > Patch > Normal SM File Hierarchy > Replace > Normal SM File Hierarchy > Compat > Normal SM File Hierarchy > Objects > Database + iconmaps.txt + inventorydesc.txt + shapesets.txt > Crafting Recipes + Crafter Name.json

Mod Directory : The name of the directory will be interpreted as the name of your mod.

description.txt : The first line of this file will be interpreted as the description of your mod. Do not create an empty description file - this confuses the loader.

version.txt : For now, this doesn't do anything. In the future, CML will interface with the Scrap Mechanic Mods (SMM) website in order to keep your mod on the chosen or latest version, and ensure it is compatible with the current version of Scrap Mechanic (as you define it on SMM). For more information, visit the page

compat.txt : For now, this doesn't do anything. In the future, any time another mod conflicts with this mod, CML will reference this file. This file allows you to declare what files to use instead (from the Compat folder), depending upon what mod it conflicted with and/or in what file. This allows you to resolve issues with mods that would otherwise conflict in a peaceful manner. In any case, this file is not required to be present. For more information, check out the C.U.R.S.E. Customizable Ultimatum Resolution System for Enigmas page.

Merge : The Merge folder takes all files, compares them with the held version of Scrap Mechanic (SM), and creates patches out of the difference between them. All files are then checked to determine if they need to be replaced with the held vanilla version by checking file sizes. If the file has a patch that needs to be applied, this is where the application occurs (How? See the Patch System page). For more information on the merger, please visit the Merge System page. Please note: Merging only works with text-based files.

Patch : The Patch folder takes all files (from all mods) and applies the patches within to a single working copy of any vanilla files that are referenced. Once all mods have applied their patches, all changed files replace their respective files in the Scrap Mechanic folder. For more information on how patching works, please visit the Patch System page. Please note: Patching only works with text-based files.

Replace : The Replace folder simply replaces files in the Scrap Mechanic folder with the given files. This is typically used only for images, textures, and other non-text files. For more information on replacement, please visit the Replace Folder page. Please note: If you want to modify the icon map, you should not use the Replace folder. Instead, check out the iconmaps.txt section or the Creating and Defining Icon Maps page.

Compat : For now, this doesn't do anything. In the future, any time another mod conflicts with this mod, it will first attempt an alternate patch as defined in compat.txt. If the incompatibility still exists, the Incompatibility Manager will take over as normal and prompt the user. For more information on the Customizable Ultimatum Resolution System for Enigmas (C.U.R.S.E.), please vist the C.U.R.S.E. page Note: All files within this folder are treated as patches. For more information on how patches work, please visit the Patch System page.

Normal SM File Hierarchy : Act as if the parent folder is the Scrap Mechanic folder. For example, if you want to Merge `SurvivalGame.lua`, you would place it in `Mod Directory\Merge\Survival\Scripts\game\SurvivalGame.lua`.

Objects : This is a special folder to make creating objects easier. It allows for a dynamic workflow. The next three files are important to setting up or porting your mods.

iconmaps.txt : This is where you define your icon maps. The format is: One definition per line: $THIS_MOD/Path/To/XML/File.xml : $THIS_MOD/Path/To/PNG/File.png The name and location can be wherever you please, so long as it resides within the Mod Directory (By this logic, the path must start with ). Please note: Your icon map should only include the icons you want to change. Otherwise, you are using up unnecessary space, and may accidentally be overwriting a modification by another mod to the same UUID. If you would like more information on how to create or define icon maps, visit the Creating and Defining Icon Maps page.

inventorydesc.txt : This is where you define your inventory description files. The format is: One definition per line: $THIS_MOD/Path/To/Inventory/Description/File.json The name and location can be wherever you please, so long as it resides within the Mod Directory (By this logic, the path must start with ). Please note: Inventory descriptions added in this way are only additive - that means that you can not modify pre-existing descriptions. If you would like to modify any inventory descriptions, please use the Merge folder. If you would like more information on how to define inventory descriptions, visit the Defining Inventory Descriptions page.

shapesets.txt : This is where you define your shapeset files. The format is: One definition per line: $THIS_MOD/Path/To/Shapeset/File.json The name and location can be wherever you please, so long as it resides within the Mod Directory (By this logic, the path must start with ). Please note: Shapesets added in this way are only additive - that means that you can not modify pre-existing shapesets. If you would like to modify any shapesets, please use the Merge folder. If you would like more information on how to define shapesets, visit the Defining Shapesets< page.

Crafting Recipes : This is a special folder to make creating crafting recipes (and recipe-centered mods) easier. This is only a container folder for the the different crafting recipe lists.

Crafter Name.json : These files contain your recipes. For an explanation on how to define new recipes, visit the Defining Crafting Recipes page. Please note: Recipes added in this way are only additive - that means that you can not modify pre-existing recipes. If you would like to modify any recipes, please use the Merge folder.

CML Modification Algorithm (Advanced Explanation)

Modifiable Folders

Currently, the following files/folders (relative to the Scrap Mechanic folder) are not modifiable:

This helps to decrease the size of the necessary version hold.

If you would like to make a case for the modification of a file or folder, you can do so on the CML Discord in the #suggestions channel.