This is an official mod development tutorial. This tutorial will help you quickly learn TerraCraft’s mod development.
【CHAPTER 1.1】 LET’S GET START!
The tutorial corresponds to the game version: Indev 1.1
What is MOD?
TerraCraft’s mod is A game content expansion package that allows players to add or modify game content, in pursuit of providing players with a better gaming experience.
The TerraCraft development concept is to allow players to freely create and play modS in an infinite map, achieving a high degree of freedom in the game. As you can see in devmods folder, TerraCraft is essentially an official mod. Most of the future game content updates of the development team will be carried out in the form of mods. At the same time, we will provide open source official mod source code for mod makers to reference and learn.
What technology is needed to develop mods?
IDE (recommended): Visual Studio Code (VS Code)
Data Exchange Language: Json
Programming language: Lua (version 5.1)
This tutorial will assume that you already have a certain understanding of Json and Lua, or you can learn these languages step by step through this tutorial. For most of the mod content, you can simply write Json for development. For advanced game content, you can write related game logic through Lua.
Lua reference materials: Lua official tutorial (English)
【CHAPTER 1.2】 Install Visual Studio Code
Visual Studio Code (VS Code) is a free, lightweight integrated development environment (IDE). In this tutorial, we will use VS Code for mod development.
Download and install VS Code
VS Code official website: https://code.visualstudio.com/
Click Download for Windows to download:
Open the downloaded installation package and install it according to the prompts of the installation wizard. Finally, the VS Code installation is complete. Run VS Code, the initial interface is as follows:
Install Lua extension plugin
Click the button on the left:
Enter Lua in the search bar of the extension plug-in, and install the Lua plug-in:
(Optional) You can continue to install a Lua Helper plug-in to improve development efficiency.
【CHAPTER 1.3】 Configure the mod environment
Create mod folder
Create a folder in the devmods folder of the game’s main directory as the mod folder of the mod to be developed, and name the folder arbitrarily.
Note: This tutorial uses “ExampleMod” as an example. Create a “ExampleMod” folder in the devmods folder. Please name the folder according to the name of the module you want to develop.
Use VS Code to open the module folder
Click the menu item File->Open Folder… in VS Code to open the mod folder you just created.
Configuration mod basic information
Click the New File button in the opened ExampleMod folder project and create tcmod.json as the main configuration.
Write the basic information of the module in the tcmod.json file.
"description": "A journey ends and a new story begins.",
"tcVersion": "Indev 1.1",
"authorList": [ "BlueYoshi", "KfcMario" ],
"credits": "Anything you want to thank.",
What is mod namespace?
The mod namespace (
modid, also known as
namespace) is the unique identifier of the current mod in the entire mod package. If there are two or more mods with the same namespace in all loaded mods, the two mods will conflict and the mod package will fail to load. Therefore, when naming modid, please choose a module namespace that is not prone to conflicts as much as possible. The namespace of the original TerraCraft is
The important role of the module namespace is to ensure that the names of all objects (such as blocks, items, NPCs, projectiles, special effects, etc.) are unique in the global space. The unique name of each object in the global space is the
namespace:idname . Through the following simple example to understand:
Assuming that two mods with the namespace
coco_worldare currently loaded, and both mods have a box called dirt, then in the global space:
tc:dirt represent the original clay blocks of TerraCraft
happy_days:dirt represents the dirt block of the happy_days mod
coco_world:dirt represents the dirt block of the coco_world mod
For all objects in the original TerraCraft, their unique names in the global space are
tc:idname, please pay attention to the difference.
Dealing with garbled characters
Please save all JSON files in UTF8 format, otherwise, garbled characters may occur during the running of the game.
The interface of the correct configuration mod is shown in the figure. Note that the JSON file must be encoded in UTF8 format in the lower right corner.
Check whether the mod is successfully configured
Run TerraCraft.exe directly, click the “Mods” button in the menu interface, if you see your mod in the mod list, it means your mod is loaded successfully!
【CHAPTER 1.4】 Understanding the mod path
Refer to the file management method of
devmods/terracraft, you can create these folders and files in your mod folder according to the needs of the mod.
- data: Compile miscellaneous configuration tables.
- contents: Store game elements and corresponding configuration tables.
- advancements: storage progress.
- blocks: storage blocks.
- block_presets: Store block presets.
- boimes: store biomes.
- boimes/surfaces: Store surface biomes.
- boimes/undergrounds: store cave biomes.
- boimes/nethers: store the hell biome.
- buffs: storage status effect.
- buildings: store buildings.
- commands: Store instructions.
- effects: store special effects.
- effect_ai: store special effect AI.
- enchantments: store enchantments.
- items: store items.
- item_ai: store item logic.
- liquids: store fluids.
- npcs: Store NPCs.
- npc_ai: Store the AI of the NPC.
- projectiles: store projectiles.
- projectile_ai: Store projectile AI.
- recipes: store recipes.
- recipe_config: store the universal recipe table.
- mod_textures: store custom textures.
- skeletons: store skeleton models.
- shaders: store shaders.
- skins: store skins.
- spawns: store NPC spawn tables.
- trees: store trees.
- languages: store language files.
- scripts: store global script.
- sounds: store sound effect files.
In general, we just open the
contentsfolder. You can freely customize the file directory structure in all subfolders in
【CHAPTER 1.5】 Learn JSON
writing JSON basely do almost everything in mod development, and the logic processing is done by writing the Lua script language. Just fill in the Json data, you can also complete most of the Mod functions.
The namespace of the JSON
Mod is initialized in the form of a JSON for all objects. All the name space in the Json is the private space where the Mod is located, instead of using the global space. If you want to link between mods, you need to point to the objects of other mods, please use the namespace of other
modname:idname. for example:
Assume that two mods with namespaces
coco_worldare currently loaded. The happy_days mod has an item called
cat_bullet. The coco_world module hopes to link with the happy_days mod. A gun called
dog_gunis designed, and I hope to use the
cat_bulletof happy_days. As ammunition.
Then the ammunition written in
dog_gunin the coco_world Json should be
happy_days:cat_bullet. If you write
cat_bulletdirectly, you will only find the name in the original item and the current mod item, and report an error if you can’t find it.
If the object name in the mod private space is the same as the original TerraCraft name, it will actually point to this object of the mod instead of the original TerraCraft object. If you want to point to the original TerraCraft object, please use the
tc:idname. Let’s give an example:
Assume that you currently want to write a mod to synthesize 9 original dirt blocks into 1 diamond, and an item named
dirthas appeared in the current mod. If you use
dirtdirectly, the dirt of the current mod will be used to synthesize diamonds. If
tc:dirt is used, the TerraCraft’s original dirt blocks will be used to synthesize diamonds.
Json registration mechanism
Before writing the first Json, you need to briefly understand what the Json is for. The game will automatically register each object in the Json when loading all mods, and then each object will get a unique digital ID dynamically generated in the game. This digital ID will not change during the entire game. This knowledge will be used in the Lua script tutorial.
If you want to write a Json, we suggest to copy the format of the corresponding Json from /devmods/terracraft/data and /devmods/terracraft/contents. At the same time, you should write according to the strict format of the Json specification. Note that the Json is filled in strictly in JSON format, and comments are not supported.
When using VS Code to write a JSON file, VS Code will intelligently prompt the place where grammatical errors occur. You can correct the grammatical problems according to the prompts of VS Code.
Generally speaking, all JSON files in the contents folder are in this format:
Among them, the idname indicates the id of the corresponding game element that is about to be registered in the game.
The materialized idname (such as NPC, block, item, achievement, etc.) should be named in lowercase + underscore + number, and the number cannot be at the head.
golden_egg, ender_zombie, ironman_mark38. these are good materialized idnames.
Functional idnames (such as block entity, NPCAI, projectile AI, effects AI, GUI, etc.) should be named using Big Camel Case (UpperCamelCase): the first letter of each word is capitalized, and the other letters are lowercased.
IronmanEffect, SuperChest128. these are good functional idnames.
【CHAPTER 1.6】 Add Your First Item
TO BE CONTINUED…