This guide will explain how to make mods for Aground Zero and upload them to the Steam Workshop. This includes example mods, hints and tools to get you started modding!
Your First Mod
To make a new mod, first find the install directory of Aground Zero (en Steam, you can right click Aground Zero in your library, Manage->Explorar archivos locales). En el data/mods carpeta, create a new folder. Inside that new folder, create a new text file called “mod.xml”, then edit that file – a text editor with xml syntax highlighting is preferred (notepad++ is a good lightweight one).
Dentro de mod.xml archivo, paste this:
<?versión xml ="1.0" codificación ="utf-8" ?>
<datos>
<nombre>My First Mod</nombre>
<descripción>Doesn't do anything YET.</descripción>
<autor>A mí!</autor>
<versión>0.1.0</versión>
<init>
Your xml and code will go here...
</init>
</datos>
For all codes you paste, make sure quotes remain straight ‘ y » – some text editors will curve them into ’ y ”, which look the same but are not understood in xml files.
Load the game, or hit Ctrl+Shift+M if the game is already running to reload all mods, and if everything worked, you should see your mod in the mods list:
If the mod does not appear, or it appears in red, there was an error – hit Ctrl+Shift+D to bring up the developer console and look for red text. A veces eso’s obvious what is wrong, but sometimes it is not as clear and you might have to troubleshoot by deleting/commenting out sections of your mod until it works again to identify where the problem is. You can also join our discord and ask for help in our #modding channel!
While this is technically a mod, eso’s not very exciting, so let’s try making it do something!
Agregar elementos
One of the simplest things you can do is add items to the game. Let’s say you decide Aground Zero really needs doughnuts. You can add them with this simple example mod.
Take a look at the mod.xml in the .zip file – dentro de <init> bloquear, there are now some tags with comment lines (dentro de <!– –>) explaining what they do. There is also a single image – doughnut.png, which is the icon for the doughnut.
En general, when adding items, necesitas:
- A name – you can add one for as many languages as you want to support.
- An icon – one you draw yourself, or get from an open source site like opengameart.org (like the doughnut icon), or even tint an existing one in game.
- The item declaration that says what it does (en este caso, you eat doughnuts to regain 150 hambre).
- Ways to obtain the item. For this mod, I added a way to cook it in the kitchen, and buy it in a vending machine.
For a mod this small, everything can be inside the <init> bloquear. Pero, for larger mods, you may want to organize them with folders and additional xml files – you can do this using <include id=»folder/file.xml» />. Just keep in mind that paths are relative to the xml that calls them.
Comportamiento
Actions determine what items do when they are selected on your toolbar. Some items don’t need ANY acción – like raw materials you can use for crafting but have no use themselves. For the doughnut example above, it used the eat action, which was already defined in the core game files (you hold right click to eat it). There are a lot of existing actions:
- mine – Mines blocks like the Laser Drill.
- place_ground / place_ladder – Sets ground flags like cables, belts, ladders.
- comer – Eats items to gain hunger and health.
- place_object – Places a specific object, optionally consuming the item once placed if consume=»verdadero».
- construir – Como place_object, but right click lets you choose what blueprint you want to place.
- artesanía – Crafts an item from your inventory – like the Assembler.
- place_block – Places a specific block, optionally consuming the item once placed if consume=»verdadero».
- pala – Como place_block, but right click lets you choose what block you want to place.
- disparar – Shoots projectiles like the Laser Gun.
- mejora – Upgrades items, this is what upgrade chips use.
- blueprint – Items that when you collect them can unlock blueprints and recipes.
- paint – Paints blocks like the painter tool.
- bucket – Can fill with water, and place water when filled.
These actions are in data/core/items/actions.xml, and you can see their full code and what they do there. Sin embargo, if none of these work for what you want to make, you can add your own actions!
Aquí’s a simple example that adds a remote control item with a custom action. When selected on the toolbar, the action lets you right click to pair with a structure if there’s a structure selected, otherwise right click to access the paired structure from anywhere. This is pretty OP, as you can now access a battery from anywhere for infinite power or storehouses to grab/drop off items. Pero, theoretically you could modify what a remote control can do when accessing a structure (or change what structures it can access), allowing you to manage your base remotely without anything too game-breaking.
This example also uses item storage to determine what structure it is currently paired with. Storage lets you set all kinds of data to items and objects that are saved. The one thing to keep in mind is that an item’s storage affects the entire stack, and two items with different storage cannot be stacked. If you want to change the storage of a single item in a stack, you have to remove it from the stack and place it in the cursor or another inventory slot (o, peor de los casos, toss it on the ground). I avoid this issue by setting the remote controls to be unstackable.
Sharing Mods
Once you have a mod, there are two ways to share them with others. The first is to zip the mod folder (con mod.xml in the root of the zip file, no folder/mod.xml), and manually give that zip file to others and have them drag and drop it into their game window (without extracting it first). This will install the mod.
The other way is to upload the mod to the Steam Workshop – allowing everyone to view and subscribe to your mod! If your mod is in the data/mods folder and does not have an error, you can select it in the mods list and you’ll find an Upload to Steam opción.
Uploading to steam requires a preview image – this image must be named vista previa.png o preview.jpg alongside the mod.xml file, and be less than 1MB. Steam displays these as square icons in the workshop, so any other aspect ratio will end up with black borders.
You then get to write notes for the update, enter the id of the workshop item you want to edit (or create new to create a new workshop item), and select any applicable tags for the mod. You then have to agree to the workshop terms of service (this only needs to be done once), and hit okay to upload the mod.
Assuming there are no errors, you will get this popup and you can select View Item to view the item in the workshop. On the right of the item, you will see owner controls where you can edit the name, descripción, and change the visibility to public so others can see it:
When you hit Upload to Steam on the same mod again, the workshop id should be pre-filled, but if it is not, you can find it in the workshop item page url after filedetails/?id=<id> (you can do this for any workshop item you are listed as a contributor). Uploading again will modify the mod files, tags and preview image, but not the name, description and other data. You can also view the change notes you entered when uploading for each edit on the workshop item page, and revert to previous edits. Once the mod is public, people will be able to see and subscribe to your mod!
Estructuras
Structures and objects allow you to put interactable elements into the world. Each object has shapes, which determine its physics bounds and interaction bounds. Objects also have their own actions that are performed just like item actions when an object’s shape is selected – sin embargo, you can disable interacting with objects for some actions when needed (like the laser gun). To debug shapes, you can use the dev code: container.showPhysics(verdadero) to show a red outline of all box, sphere and cylinder shapes. Keep in mind if modelBottom=»verdadero», the main model transform will be repositioned so the origin is at the bottom of all shapes, so moving the shapes up and down will not move them relative to the model if this is true.
Aquí’s a simple example that adds a switch item that uses a place_object action to place an interactable switch in the world. Most of this will be familiar to you from the item examples, except now we need a switch object that can be placed, and removed (to collect it).
Like with the custom action, switches have a getSelection event to set the tooltips and an onAlternate action that removes the switch. Sin embargo, they also have an onSelect event that toggles the switch on and off – this utilizes the POWSTRUC and SWITCH ground flags (POWSTRUC is under powered structures, and looks like a cable, passing power through, SWITCH looks like a cable too, but does not pass power through).
3D Models
One big thing objects need that items didn’t is a model – something to display in the world. You can re-use existing models in game, tinting and repositioning them like I did in the switch mod. In general it’s probably easier to animate models in a 3D modeling program, but you can see I did a very simple 2 keyframe animation for the switch moving on/off.
If you want to add new 3D models, whether you model them yourself or find them on a site like opengameart.org, you need to convert them into wobj files. You can do this using the command line application CreateWOBJ aquí.
CreateWOBJ expects the first command line argument to be the input model, and the second argument to be the output wobj. It uses assimp which supports a huge range of formats you can view aquí. CreateWOBJ supports bone and node animations, but not mesh animations (vertex-based animations, these are pretty rare nowadays). CreateWOBJ merges all meshes, materials and animations into one file – tú’ll specify textures in xml. Aground Zero does not support multiple textures per wobj – either pack the textures into one mega-texture, o (si necesario) break the object into multiple wobj files.
While all meshes are merged, you can add -writemeshes as a third command line argument which will write the names and vertex subset for each mesh in the object – this is useful for making subsets – which you can see in the subways and for the player hairstyles (all of them are packed into one wobj).
Once you have a wobj, eso’s time to define it in game. You can do this with:
<model id="nombre" path="path to wobj" texture="diffuse" normal="normal" emission="emission" />
You can use the same model many times, changing the textures. Aground Zero only supports 4 texture types – diffuse, normal, emission and specular. There are plenty of guides on what these are, but you might have noticed that specular is not defined on the model line. This is because specular is packed into the otherwise unused alpha channel of the normal map. To modify the alpha channel of a normal map (after the normal map has been loaded for at least one model), you can use this command:
<setSpecular normal="normal_map" specular="specular" scale="scale" />
While the specular channel must be grayscale (eso’s a single alpha channel), 0 is black, 0.5 is equal to the diffuse color, y 1 is pure white, interpolating smoothly between. The scale is optional to brighten or darken the specular map, and defaults to 0.5. If the specular parameter is not a primitive texture (like white or black), then it will be unloaded after this command and cannot be used again unless you add unload=»FALSO» to the command (as usually you don’t need the specular map once it’s been packed into a normal map). si no’t want to deal with normal maps or specular maps, there are three primitive textures you can use: no_normal (the default, normals unchanged and 0.5 specular), no_specular (like no_normal, but black specular) y glass (white specular).
For coordinates, x/y is the ground plane, and z is up (think mining depth). Most modeling programs have x/z as the ground plane, and y as up, but CreateWOBJ automatically rotates models to account for this.
Billboards
If you absolutely don’t want to use 3D models, you can place billboards or primitives. Primitives are simple shapes (quads, cubes, esferas) that can be defined like models above, but you use primitive=»…» instead of referencing a wobj. Billboards are 2D sprites that are always facing the camera. This looks okay for small, spherical or cylindrical objects, but often looks like it’s moving when the camera rotates. You can add billboards with this code inside an object:
<billboard tile="teja" animation="animation if desired" type="tipo" scale="size in meters/blocks" offsetX="x position relative to center, you can also have an offsetY and Z" />
Type can be normal (no blending, low alpha values are discarded), transparent (allows blending, if you need semi-transparency), emissive (glows in the dark/not affected by lighting), indicator (visible through walls/other objects).
Billboards can also be added to objects with 3D models (with the xml tag, o object.addBillboard), and is how warnings like out of power are added in game.
Planos
los cambiar example is an item, but most structures in game are placed as blueprints with the Fabricator and then built or dismantled. You can do this by making a structure that extends the blueprint structure, then set a type (fuerza, produce, base, vehículo, decor), información (the structure it will build) and a recipe that sets the materials, power cost and time to build the blueprint. los factory_blueprint is a good example of this. You can also set an animateIcon function for the blueprint, this will animate the structure in the Fabricator list when it is hovered (but this is optional). There are lots of structure types you can extend – me gusta artesanía for factories, grow for item producers, manned_craft/manned_grow if they need an NPC to operate them, y más. Once you have a blueprint, you can add them to the Fabricator using this command:
unlockBlueprints(state, jugador, ["blueprint_id"]);
Materiales
To add new blocks or ores to the game, you need to add materials. Materials have a name, a texture (can be set on all 6 sides), a mining power and optionally an onDig evento.
Textures are 256×256 imágenes, which actually make 2×2 bloques (each 128×128 quarter of the image is one block). It should be looping, and must have a normal map. Laigter is a good tool for generating normal maps from images (I’d set bump to 0, and enhance height between 60-100 and softness to 2-3). You can use the visualization to see how it will react to light sources in game. Textures are defined like this:
<texture id="cave_floor" color="cave_floor.png" normal="cave_floor_n.png" />
All textures must be the same size (they are placed in a single texture array), but for texture packs you can change it from 256×256 as long as make sure all textures are the new size. It will still make 2×2 bloques – if you want all blocks to be the same, you can just duplicate the top left quarter four times.
After defining a texture, you can set the specular value of the normal map just like models:
<setSpecular normal="cave_floor_n.png" specular="negro" />
Materials do not support emission textures – their emission is set to the grid texture when placing structures.
The material can then be defined like this:
<material id="cueva" sides="cave_wall" bottom="cave_ceiling" top="cave_floor" mine_power="1" />
You can set the textures using texture=»» for all 6 sides, sides=»» for all sides excluding the top and bottom, y arriba, abajo, izquierda, Correcto, atrás, frente for setting specific sides (and this overwrites textures set with texture=»» o sides=»»).
Additional material parameters you can use:
- mine_power sets how strong your laser drill needs to be to break it (don’t add it for unbreakable blocks).
- nombre sets what name is displayed in the materializer (pala), and defaults to material>id.
- bloqueando – whether objects can pass through the block.
- ramp – whether the block is a ramp.
- block_water – whether the block stops water passing through.
- block_light – whether the block stops light passing through.
- artículo – what item to drop when the block is mined.
- opaque – a comma separated list of what sides of the block are completely opaque. If you are using semi-transparent textures, you should make sure those sides are NOT set to opaque.
- step – what the footstep sound should be for the block.
- visible – to disable rendering (it can still block objects/water).
- paint / paintable – for the painter tool.
Every block can actually have two materials – the base material, and an overlay material. Overlay materials are used for ores, and decorative elements (like the painter tool). Both the base and overlay material can use artículo to drop an item, and have a separate onDig evento. Overlay materials do NOT affect the mining power of the block though.
los onDig event runs whenever the tile is mined by an action. It passes a dig object that includes the area, object that performed the action, x/y/z position of the block, and material. This could be used for the hurting a player (or enemy) if they mine a block, or for granting an achievement when you mine a certain amount of them (like diamonds).
Áreas
Once you have materials to work with, creating new areas is all about placing blocks and objects. Areas need to have a width, altura y profundidad colocar. Any blocks placed outside these bounds will be rendered, but not saved or interacted with (this is how the city in the distance is made on the surface – it is actually re-generated from a seed every time the area is loaded). Areas also need a ground set, which determines how cables, belts and ladders are displayed. You can probably use the default for most areas. Creating areas can take a bit of work, although there are utility functions in the Generate class that can make it easier.
Additional area parameters you can use:
- gravity – if you want low gravity (or inverted gravity) mundos, you can change this from the default (1).
- belt_power – how much power each belt consumes per second (defaults to 0.05).
- waves – a normal map for the surface of the water.
- bubbles – an image for bubbles in water.
- dust – an image for dust floating around lights.
- has_oxygen – if false, then you will only recover oxygen inside vehicles or objects that produce oxygen (de lo contrario, everywhere that’s not underwater).
- break_tile – the tile to use for breaking blocks.
- break_anim – the animation (frame by frame) for breaking blocks.
- break_emit – how much the breaking block animation should glow in the dark – 000000 for not at all, ffffff for completely (this is a color, so you can change how much each channel emits separately).
You can also use the atmosphere tag to add a skybox, sunrise/sunset to the world, but keep in mind this is likely to change (and become more flexible) once I add the moon.
En <infoInit> you can also set the following parameters:
- shadow_z – if the camera is above this depth, then the sun’s directional light and shadow map are enabled (otherwise disabled).
- infinite_water_z – all water at this depth and above at the edge of the world is extended out to infinity. This was added to stop the underground river from being extended to infinity, which caused rendering issues (infinite water must be simple/convex).
- waterColor – the color of the water. The alpha channel sets the density of the water/how thick and murky it is.
- waveScale – the x/y scale of the wave texture on the surface. z/w is for a second copy of the wave texture added on top.
- waveSpeed – the speed the wave texture. Una vez más, x/y is for the main texture, and z/w is the movement of the added copy (breaks up obvious looping).
- waterSurface – like waterColor, but for the surface of the water, which should be a lot darker (mostly reflective) and higher density (can’t see stuff under the surface easily).
- bubble_size – The scale of the bubble texture.
- bubble_strength – How visible the bubble texture is.
The Ore Cave is a good example of how to make a new area – verificar data/core/world/ore_cave.xml in the game install folder. It has a <generate> block to create the ore cave, and also defines an ore_cave_portal y ore_cave_exit object that lets you enter and leave, the ore cave (de lo contrario, tú’d never be able to reach the new area). The ore cave is also cleared when all players exit it, and reloaded in the ore_cave_portal, making it a temporary area that has new ores and a new layout every time you enter.
You are allowed one area per id in the game state (aunque, like the ore cave, you can clear and re-generate for temporary areas). Areas will only be generated the first time you call state.createArea(id), or if you manually call area.generate.
vehículos
Vehicles are objects like structures that the player can mount and move around in. A lot of the logic behind vehicles is already handled by the structures mountable y vehículo you can extend (defined in data/mods/full/objects/vehicles.xml).
Vehículo is a mountable object that has an inventory, locator and can be teleported to (like the sub and boring machine). Chairs are the only plain mountable object.
Ahí’s a lot going on with vehicles and I’m not going to explain it all here, pero yo’d recommend taking a look at the sub and boring machine definitions. You can override most of the gui and controls if needed when riding a vehicle.
Enemigos
Like vehicles, enemies are complicated. The key is that you want an onFrame event (which literally runs every frame for every instance of that enemy), and perform logic for moving and attacking there. While you want to keep this relatively simple for performance reasons, allá’s no real limit to what you can do here. Adding a reaction time to enemies is usually a good idea – like how hunter bots will only search for nearby players to shoot every 10 marcos (reducing the load per frame), and will only search for nearby structures to shoot every 60 marcos. yo’d take a look at existing enemies in the game, perhaps extending them if one suits your needs.
Traducciones
Translations can also be added to the game. This is the same as in the original Aground, so take a look at the Aground translation guide.
The only difference is that you should add the language xml to your mod folder and the incluir tag to your mod init block instead of directly modifying the core language folder. Además, en el <lang> tag, you can add versión=»0.2.2″, which should be set to the game version you translated (displayed on the title screen). Si versión=»» is missing, or is a version other than the current version of the game, the language will show up as red in the options menu, meaning it is potentially out of date.
