Step-by-Step Mod Making Tutorial

Overview

This is a step-by-step guide to starting your first mod.

To start, some preparations.

First off, decide what editor you like to use. For this guide I’ll be using notepad++ because of the organizational benefits, and as such it is step one of this guide:
Download Notepad++[notepad-plus-plus.org]

Install Notepad++ then continue.

Open your computer up to C:UsersYourComputerNameSaved GamesReassembly
(Hard drive location and computer name may vary)

Find cvars.txt in Data/ and change:

to

or if you can’t find “kWriteBlocks =” add it in after kWormholeRadius =

This will output a list of the games blocks into a lua so you can see examples of all the blocks contained within the game. When beta is released, this will also output a list of shapes. The files will be output as:

C:UsersYourComputerNameSaved GamesReassemblyDatablocks.lua
C:UsersYourComputerNameSaved GamesReassemblyDatashapes.lua

So run the game to output those files.

When you have the files, open the cvars.txt back up and add a # with a space in front of kWriteBlocks to stop it from outputting the list over and over again every time you run the game. I recommend making a shortcut to the Saved GamesReassembly location on your desktop so you can get there easier, if you haven’t already.

Organizing to quickly implement templates to build on.

If you open blocks.lua with notepad++, if it’s your first time using notepad++ you’ll end up with something like this:

So there are a couple things we can do to help make things a lot easier. First, change the Language to Lua. (At the top, Language -> L -> Lua)

Then, we’re going to organize it so we have a value on every line. To do this, open a find and replace dialogue box. Press CTRL+F and go to ‘Replace’. Set it to find , and replace with ,n with the *Extended Search Mode ticked in the lower left. Press ‘Replace All’.

(Image thanks to sumplkrum)

After that completes, run
Edit -> Line Operations -> Remove Empty Lines
followed by
TextFX -> TextFX Edit -> Reindent C++ Code ***

*** To use TextFX, you may need to install the TextFX Character Plugin. All you need to do is run the plugin manager within Notepad++ Plugins -> Plugin Manager -> Show Plugin Manager -> Available tab -> TextFX Characters -> Install

You should now have a more or less perfectly organized file. The exceptions are in the blurbs sometimes where a comma was used in the descriptions, but it wont matter because we’re not going to be using this file for anything other than grabbing templates that are already organized.

So now, save the file. When you reopen it, it will be organized.

Starting your mod, finally

Okay onto actually creating your mod.

To start, I would recommend setting a faction goal (style) and name. For this example I’ll use “Military Tech” and “The Warriors of Thrirtir” (Literally used a random generator). I urge you to define these as early as possible and decide what kinds of things that faction would use to their advantage, as you can add things that will add ambience to your mod.

You should also decide whether you want plants or buildings or neither. You can also have the default plants in varying intensities (which give resources after a while). Note however, that I don’t believe you can have “only buildings” as ambience if you also have a plant launching weapon – because the plants count as ambience and will spawn in conjunction with buildings, so unfortunately it’s one or the other. This will come into play a lot further down the road, but you should decide earlier on what you think it will look like in the end. For this example I’ll cover both when we get there.

Another decision that must be made is faction ID. The wiki recommends numbers between 20-99 and 200-??? (probably 999?). I would recommend a number between 200-999 personally, and avoid 200-300 (just to leave them for someone else). For this example I’ll use 255.

Lastly you need an area to define blocks IDs. These are the numbers that will load the blocks for your faction and give them a unique place to be loaded by game without interfering with already defined blocks. The base game has a large gap between 16136-60100 (although I think mods can’t go over 26000, so let’s say 16136-26000). Any blocks defined in that area should be fine, so let’s say I want my mod to start at 18500, and each added block increase that number by one.

So for my mod planning I’d have:
Style: Military Tech
Name: The Warriors of Thrirtir
Plants?Buildings?: (Both for this example)
Faction ID: 255
Blocks ID: 18500
Notes: Dakka, shields, thick hull (example notes based on ‘style’)
Colors: Red, Dark Grey, Orange.

Now pat yourself on the back because these are some of the most important and yet easiest things to decide. I personally write on paper, but you can write this kind of file into a txt or whatever medium you like. If you’re ever stuck you can basically open this up and remember what you were originally trying to achieve.

Add your mod folder and start populating contents

So now open up:
C:UsersYourComputerNameSaved GamesReassembly
and add a folder called “mods” and within that folder give your mod a title with a new folder.

So for example, I now have Saved GamesReassemblymodsThe Warriors of Thrirtir

In your new mod folder you can also add a folder called “ships” that will be relevant later.

Add a blank blocks.lua file (if you’re having trouble with this, just make sure it’s a lua and not a lua.txt by saving it out from notepad++ as a lua).

Let’s add a block now to show you the process that’s involved from here on out, and then we’ll go into more advanced block properties later. So open up the organized blocks.lua (it may already be open in a tab in notepad++) and locate block 800. This is the terran command module, that I would like to use for my mod. So what I’ll do is copy the block of text that defines 800 and paste it into my own blocks.lua like this:
You’ll notice that I also added another start and end bracket, so the file parses correctly.

Then we have to change it to fit the parameters of our mod. So we get this:

So now, when you boot the game you can go to Mods on the main screen and scroll down until you get to your mod, which should have 1 error. It will tell you that it doesn’t define any ship and that’s fine for now.

Go into sandbox mode, and to start off with press 3 (with the mouse outside of the console) to enter edit/construction mode and highlight the text that’s there and press delete. You could also type clear into the console but I want you to see that you are able to highlight blocks in the sandbox (and imo it’s easier to press 3 and delete). Now, mouse over the console and type ‘palette 255’ (replace 255 with the faction ID you’ve chosen to be using).

Congratulations, you are looking at your first modded block. If you want to pilot it around, you can left mouse button click it once and then press 1 to enter fly mode, which will give you control.

What is a group? What is a faction?

Now you may be wondering why group and faction adopted the same number. They didn’t have to. The group number is simply the group that contains the blocks, and it’s easier to have them as the same number. There are more advanced things you can do with groups, but I’ll allow people to discover those things on their own as to not cover every single exception in this one guide. Chances are, if you’re looking for a way to do something, you’ll find it.

Basically though, the first thing you should do when you copy a piece over to your mod from now on, is change the ID, change the faction ID# and change the group # to match your faction’s necessities. Another thing that becomes more common is color, which I wont really touch on, but basically it’s in hex and there are a lot of ways you can obtain color hex codes.

This is probably as good a time as any to actually create the factions.lua you’ll be using for your mod. Create a new document in notepad++ and copy this:

…and change a couple things, first off you wont need start=”255_startership”, yet so you can backspace it out (we’ll come back to this later). Also change 255 and ‘The Warriors of Thrirtir’ to your own faction ID and name, if you haven’t already. Save the file as factions.lua

Less important notes about factions.lua
That’s about all you can do with factions.lua. There are more AI Flags that you will read about in other guides or the Anisoptera Docs page, but I’ll leave those alone so you can test them out. These AI Flags are set to be quite agressive though, so if that doesn’t suit your mod style you should think about changing it. There’s a way to make them even more agressive as well, but then they are reckless to the point of endangerment. This is a good balance.

You can also add a third color with color2=0x###### (###### = Hex Code) and changing “primaries=#” to 3 if you want. I’m not entirely sure what the third color does, as I’ve only made a mod with 2. I may actually test this at a later point and update the guide.

Another thing I’ve seen people do with factions.lua is define another faction entry for meta that gets called in regions.lua instead of the one the player uses. This would be something akin to having ‘Space Marines’ as a faction, but in the game you fight “Storm Lords” (a chapter of Space Marines). To set it up, you make the meta faction playable=0 (not player selectable) and you don’t need to define a startership. This is somewhat advanced, but just to give an idea of what’s possible.

Block editing. The belly of the beast.

So you’ve seen a basic piece if you’ve looked over the blocks.lua output file.
They usually consist of:

A command definition
A shape definition
A Scale
A name
Features
A group
Properties

The first 6 are pretty straightforward, and usually followed by a blurb=””, property. The most unknown here to people are probably the features, and the best way I can describe features is that by adding a feature you extend the properties to be able to load more attributes that you will need on your block. I’m going to make a table that lists the extra properties associated with each feature here. For more information on each, there are other guides and even the official docs[www.anisopteragames.com]

This doesn’t cover all of them, but some of the more useful ones. Also note that you don’t have to use all of the feature’s properties, but if you notice that something has a property you didn’t give it, you can forcefully change it by defining it to be whatever you want in the blocks.lua.

Small note before continuing: 1 standard square block is 10×10 units., and the same units are used for defining radii. There are ways to get measurements in the game this way, by creating rulers of blocks or clicking blocks that have a specific radius. You can even make ruler blocks by giving a weapon a radii of 500,1000, etc. if it makes your life easier.

Every feature is spearated with a | character. (Vertical bar).

FEATURE

• Extra Properties
• Extra Properties
• etc

AVAILABLE WITHOUT FEATURES (If you just need a block)

• group
• lifetime
• points
• durability
• blurb
• fillColor
• fillColor1
• lineColor
• capacity
• growRate

COMMAND
Allows the block to be piloted and adds some new moddable subproperties to command{}

• sensorRadius
• blueprint
• aiflags

THRUSTER

• thrusterForce
• thrusterBoost
• thrusterBoostTime
• thrusterColor
• thrusterColor1

TORQUER

• torquerTorque

GENERATOR

• powerCapacity
• generatorCapacityPerSec

Note about GENERATOR feature: It causes the block to explode in a fairly large radius when destroyed. I think the actual calculation is something like 1.2x the HP (so a 150HP generator will deal 180 damage when it explodes). Someone discovered this can be prevented by adding a THRUSTER feature and just putting thrusterForce to 0, which causes the generators to be destroyed without exploding. Please don’t abuse it… this can tip a mod from balanced to OP pretty easily.

TURRET

• turretSpeed

CANNON
Adds cannon={} which has the subproperties:

• roundsPerSec
• explosive
• muzzleVel
• power
• damage
• color
• range
• explodeRadius

LASER
Adds laser={} which has the subproperties:

• explosive
• pulsesPerSec
• pulseAvailability
• power
• width
• damage
• color
• range
• explodeRadius

CHARGING

• chargeMaxTime
• chargeMin

SHIELD
Adds shield={} which has the subproperties:

• strength
• regen
• radius
• color
• lineColor
• damagedColor

LAUNCHER

• replicateBlock

TRACTOR

• tractorRange

MELEE

• meleeDamage

TELEPORTER

• teleporterPower

PHOTOSYNTH

• photosynthPerSec

And there are some that I’m not sure what modifiable values they add, but they add functionality:
Note that some of these may require a specific shape. I’ll update this section when I can, but just look at base game examples for where they use these.
ASSEMBLER
CANNON_BOOST
ENVIRONMENTAL
EXPLODE
FACTORY
FREERES
INTLINES
INVISIBLE
NOCLIP
REGROWER
ROOT
SEED

Some overpowered ones that may make for a bad mod if used:
DEACTIVATES
INVULNERABLE
TELESPAWN

More exist, but they are usually used by the game to carry out the events that these ones create. I encourage you to use the docs[www.anisopteragames.com] and run a find (ctrl+f) to learn more about any specific feature. If you’re still having trouble, search other guides or ask in the comments.

Completing your blocks.lua

So now that you’re accustomed to what a block is and how to add features to it, you’re going to want to add a number of blocks that fit your faction’s style. The bare minimum I’d say is required for a mod is:

• A command block
• A hull piece
• A thruster
• and a weapon of your choosing.

Note that for the ability to use < and > to change the size of a block, as long as the block has the same name, shape, and features, it will give you that capability if the scale of the blocks differ. For example 803,804, and 805 are the terran thrusters. All that changes between them is the scale and the blurb. Also certain blocks require you to have a mirrored version, like RIGHT_TRI2R, which for every one defined needs an equal piece but with the shape as RIGHT_TRI2L.

Once you’ve populated your mod with enough blocks, there’s a couple things you’re going to want to start doing:

To change the HP of a block, you need to change durability. If you have a set path for the math you’d like to use, and you know the HP but not the durability, I would recommend using the Reassembly Web Development Kit by TTFTCUTS[atg.lychnobi.com]. Make sure you set the scale and shape properly though, because the values depend on area, which changes with block scale and shape.

To modify the weight of a block you need to change density. Like HP, it depends on area, and it’s a lot easier to use the Reassembly Web Development Kit by TTFTCUTS[atg.lychnobi.com] to get exact values. Again, make sure your scale and shape on the block is correct.

Once you get some weapons implemented, you’ll want to test them a bit. I wont go into balance right now, but for basic tests you can use console commands like “target” and “asteroid” to spawn entities to shoot at. You can also use ‘palette 100’ to load the text blocks if you’re accustomed to shooting at the text and happen to destroy them all. Remember that each text block alone is about the same health as a capitol ship’s HP to their command core (in a line, anyways), so if you’re blowing those up easily you made need to make some changes. I would also recommend selecting your whole ship and alt+dragging a copy up to the top left for testing, because if you make a mistake you may have to rebuild a ship.

Pretty straight forward, if you don’t like the colors of your mod, change them.

To export a ship, you need to double click it and make sure the ship has a green box around it with only 1 red triangle (center of mass, if more exist it means there are pieces not attached). Then use the command ‘export (shipname) (author)’. This will output a file to your saved ships location which can be changed in the cvars.txt under kExportDirectory (for example: kExportDirectory = “F:/Games/Reassembly/ToSort”).

To import a ship you need the entire string for the ship location, so it looks something like:

Side note: A newer version coming soon will only require ‘import’ to be typed, which will open a file browser to locate your ship’s files.

Chances are, if you’re making ships too early and saving them with ‘export (shipname) (author)’, if you try to load them back in after making changes to shape or scale, they’re going to be a mess of pieces. Sometimes it’s better to start from scratch than continuing to build on failed designs. Learn to live with it and move on.

Advanced Testing & Balancing (or not)

So you’ve probably exported some designs you like, and if you haven’t, you probably should. At the very least, make a small fighter ship.

This is where testing comes into play. Hopefully you have a large bank of ships with varying P costs you can test against, if not you can use the wormhole[www.anisopteragames.com] and look up people’s ships. Basically though, you should open the tournament screen and pit your designs against some of the vanilla faction ships at the same P costs. When you get a result there’s one question you should ask:

Should it?

As in, if your ship wins, should it? Sometimes the answer should be no, othertimes the answer is yes.. and there are rare times where it should win but it’s a limitation of the AI so it’s alright the way it is. When you realize that your ship is winning a fight it shouldn’t, there may be a problem with a number of things that could be anything aside from the name and blurb of your block (s). You can identify what it is by just asking yourself that question, should it? For example if you notice a piece of your ship grow back too fast, should it? And then make the appropriate changes so that the mod and tournament matches play out how you think they should. Sometimes this involves accepting a loss because your ship was poorly put together, or even accepting an overwhelming victory because you understand that something else is just as large of a counter to your pieces.

There’s a bit more too it than all of this, as in, you should still perform as much math as you can for dps/range/muzzleVel and how they relate to points within the main game, but this helps resolve situations where something is wanted in a mod but you need to balance it around, for example, density – which is impossible to see on paper.

Another way you can test some designs while you’re building a ship is, if you have a number of ships that you’ve created in sandbox, you can highlight them and type ‘pool’ into the console which will pool the selected ships against eachother. Sometimes this bugs out though, so pay attention to the round start and if things start falling off the ship(s) it means they’re not properly set and you’ll need to export and reimport them.

Finishing up

There are a number of advanced topics at the end here.

So to start, let’s finish factions.lua. Remember when you backspaced out start=? Well now that comes into play. Make a 300p ship from your faction blocks in sandbox and save it out. Locate the file and relocate it (either copy or cut) into your mods ship folder and rename it “YourFactionID_startership.lua” or something along those lines anyways. For example, 255_startership.lua. Then in your factions.lua, add in:
start=”255_startership.lua”
If you’re having trouble, look back at the section titled ‘What is a group? What is a faction?’

Regions are probably the absolute last thing you want to implement on your mod. The file basically defines how a sector in the world is going to be drawn, and where to draw them in the galaxy. It also defines how many fleets the sector will have, and/or how many ships in ‘P’, as well as what kinds of ships are guarding against other factions from rescuing station cores. Honestly, it would be easiest to just follow the Reassembly Web Development Kit[atg.lychnobi.com] information to create one, and if you have any problems post in the RWDK discussion on steam’s community board (or in a new thread), and someone will help.

I would recommend copying one that you like and editing it, or saving one out of RWDK, as opposed to making one from scratch.

The basics:
count – Number if circles (radius) drawn around the map (not linear, they are randomly placed)
position – The center of your radius (defined next) falls anywhere in this position
radius – The radius where sectors may populate with your faction’s ships
type – Any of these are good, voronoi is the most organic shape generator

fleets – Inner weight and outer weight are P related, so 12000 5000 would put fleets up to 12000p in the middle and 5000p near the outer rim (If you’re using RWDK, expand group and add new item)
fleetCount – Min/max number of ships in each fleet
fleetFraction – Leave this default, seems to work best until anyone figures out what it does

fortress – These are the ships that are spawned around broken enemy stations. You can define more than once ship if you want. It reads these from /ships/ in your mods folder and follows a similar naming convetion to the startership so for example ‘255_staticwarship’. These are oftentimes without engines, but don’t have a factory block like a station would, but they can also just be ships.
fortressCount – The number to spawn around a broken station the enemy has to capture
fortressRadius – Distance from broken station center to place fortresses, min/max

unique – This allows you to define unique fleets, using the ship names to define their contents.
uniqueFraction – As far as I can tell this is the ratio that will spawn unique fleets, 1 being always, but will only work if you only have 1 unique fleet defined. Most people leave it at default.

To test your regions.lua there is an easy way and a hard way, and both are good for testing. The easy way is to open sandbox and type ‘region factionID’ so for example ‘region 255’. This gives you a preview of what your regions will look like, but isn’t always accurate. The other way is to create a blank save as a vanilla faction and open the console with and type ‘reveal’ then close it. Then open the map and view the areas that are loading your regions (if they’re spilling into the borders of the map but say that the sectors are empty, you’ve created a bad regions file). To quickly get to the sectors you should memorize the map a bit and then open console and press ‘3’, which allows you to freely move across the galaxy.

Once you’re all set up, I find the easiest way to create a faction image is to set playable=2 in factions.lua, start a new game as your faction, then save and quit and right click the save and export as mod. This creates a folder like: ‘save0_SUDDExc’ in your mods/ folder, with an image. Take that image (usually the starter ship unless you’ve done something funny) and paste it into your own mod’s folder, then delete the mod ‘save0_SUDDExc’.

When you build buildings in sandbox make sure the small rectangle from the root piece is facing downwards. To have them spawn, you’ll need to put them into YourMod/ships/ with a similar naming convention to the starter ship (factionID_buildingname). When ambient is set to -1 in regions.lua, they will spawn around asteroids if there is enough space.

Plants are kind of like buildings except that their pieces are usually in group=5 instead of your own faction’s group (unless they’re friendly plants, such as the ones in Meat Faction). To have them spawn, you’ll need to put them into YourMod/ships/ with a similar naming convention to the starter ship, but depending on how you have them set up they could need ‘5’ as the faction ID (factionID_plantname). When ambient is set to -1 in regions.lua, they will spawn around asteroids if there is enough space.

Always check for errors when you start your mod up. Chances are you missed a bracket or something, but otherwise it should usually show 1 error at first (no startership) and the second most common error is forgetting to change the block ID, so 2 blocks are defined as the same block.

You can create folders for cvars.txt mods instead of modifying the base cvars.txt. I would say though that you shouldn’t actually include a cvars mod with a blocks mod EVER. Also no one really cares for cvars mods unless they do something very specific, and there are already mods out there that change the most used values.

If you want to source a workshop mod’s blocks, you can view all of your workshop mods on your computer at the following filepath:
Program Files (x86)Steamsteamappsworkshopcontent329130
Not sure if it’s 329130 for everyone, but thats the general location.
If I’m looking through a mod’s files I’ll usually copy them to a custom ‘Tests’ folder in Saved GamesReassembly (not mods). If you want to modify a faction and have them in your game you can add them into your mods folder with a new folder name, but there are a couple things you should do before you boot the game:
1) Make sure that the folder doesn’t have a steam_pfid (not entirely important, but still)
2) Make sure it wont conflict with any other mods. This means, if you have your mod as faction 20 / group 20 and you’re trying to load in a mod with those same numbers, there’s going to be a conflict. The same goes for block IDs. If you change a mod’s facion and group number, make sure to change it in factions.lua, regions.lua, and on all the ship names and ship files to completely convert a mod to a new ID. This can be done with a simple find and replace function: find ‘faction=20’ and/or find ‘group=20’.
3) Make sure you rename the faction in factions.lua. I’m not sure if this causes a conflict always, but just try to make it something new, even if it’s just like “New ____________”.
4) Like I said 2 paragraphs ago, check for errors on startup. If you have any, immediately close reassembly to resolve them and try again.

If you have any basic questions you can ask here, but anything more advanced and you’re on your own. Try to find examples in mods that exist, or if you want you can ask me for an example of a mod that does something and I could give you some. I may make another guide for more advanced editing like adding cooldowns and stuff, but this should do for now. I wrote this as a basic intro more than a full guide, so if you’re happy with being able to load blocks into the game, you should try to move on to the more advanced guides. If I missed anything integral, let me know.

FAQ & Limitations

In order for blocks to appear in the constructor screen, they must be used in a ship design that is contained in your ships/ folder, with the proper notation (faction#_shipname).

The easiest way to test, is to make sure your mod has no errors on the mod screen. The most common errors here are:
*Make sure that your block IDs aren’t overlapping. Every block needs a unique ID.
*Make sure that your block is in the right group.
*If you’ve put INVISIBLE on the block, it wont render, but it should be there if you highlight the entire palette.

Anything other than those and most likely you will be having a host of other problems.

This is most likely because you don’t have enough energy to fire the weapon, or the weapons demands too much energy. If you’re still in sandbox you need to enter fly mode (if you haven’t already, by pressing ‘1’) and then hide the console, in order to see your energy. The way a weapon uses energy is with the power property (usually subproperty of cannon, laser & launcher) for each shot. This means if you have 5 rounds per second and it costs 400 power to shoot, you will need 2000 energy/s to fire continuously. Note that sometimes firing continulously isn’t always how you want people to be using a weapon.

This is usually because you haven’t defined a color or defined the color as black (or with absolute 0 alpha). Color is in hex with the first 2 digits as alpha, aside from the prefix for hex (0x). So the code is:
0x HEX ## Alpha ## Red ## Green ## Blue
Alpha will make the beam see-through (to the backgroud, which in this case is space with stars). Again, there are a million ways to find hex codes. If you really need help, just ask.

This takes a lot of testing to determine either way. The easiest thing you can do is to create multiple versions of a block at first (all with different settings) and test them in tournament. Whichever one then behaves correctly, start expanding on. A way you can test it in sanbox is with the ‘target’ command that generates a block with a bunch of commands to shoot towards. This isn’t always the perfect test however, because the target itself has low hp blocks. You can also slow down time in tournament, and even open the console and pause and frame by frame to make sure that the events are playing out how you would like. If you still can’t find an AI that you want – it could very well be a limitation of the game and you’re going to have to just go with the best you can or maybe find an alternative method.

Cost is directly related to points. Don’t worry about the cost of block, as this is a goal for people using your mod, should you post it to workshop.

This is a list of conflicting flags that will crash your game if used, or cause other glitches.

(Structures with no thusters and a ROOT).
As far as I know, putting environmental blocks in a building design will cause crashes if anything grows on them. I could be wrong about this*

This will cause a crash. Don’t do it. ROOT blocks are used to attach a building to an ENVIRONMENTAL block (like asteroids). Ships can, however, contain ENVIRONMENTAL.

Pretty straightforward. Regrower is usually used on seeds, assembler is used on command blocks.

Pretty much everything spawned unless from another factory. Buildings may be able to use FACTORY if the mod has default buildings with them, but they wont work correctly if spawned from a root launcher.*

I would recommend using few melee pieces until this is fixed, but there’s a bug that can cause ships to not asssemble correctly if melee pieces are growing out from the command block. Basically, try to not make a mod rely entirely on melee, unless you have a good plan.

Unfortunately for us missile swarm lovers, there’s a bug that can cause a ship to be uncontrollable if too many missiles are equipped. Don’t let this discourage you from creating the mod you want, but if you find your ship steering akwardly while firing missiles and moving, you could be a victim of this bug. I would say not to let it discourage you (unless it’s extreme, like I actually had to abandon a mod because of this bug) because it may be fixed in the future.

At least I’m pretty sure this is true. If someone happens to test it and it is possible, I’ll update this.

*I haven’t done much with buildings tbh so if someone wants to fill me in, give me the facts in the comments.