A Comprehensive and Updated Faction Modding Guide [WIP]

Overview

If you’ve ever asked any questions about how certain mods accomplish their modern features, or just want a helping hand in learning to write your own mods, this guide was made for you. This guide will go over every single feature you can add to your faction so far, from the ground up. And when I say every single feature, I mean it. Nothing will be left out, and I expect someone who just bought reassembly to be able to make a mod using this guide. I will make a mod alongside the creation of the guide that covers everything you’ll need to know to make it, from basic creation to advanced systems. The mod will be released at the same time, and will have all of it’s features explained in this guide.The faction I have made in this guide can be found here.

Contents

First off, I’m going to separate each section into a specific purpose.

Letter A will be all about creating a mod from the ground up, with detailed explanations every step of the way. This will include how to make every functional part you could want in your faction.

Letter B will be about balancing every aspect of your mod to varying strengths.

Letter C will be advanced tricks and things to add to your mod once you understand the fundamentals. This will include fragments, custom shapes, and shrouds.

Depending on your skill level you can start with your letter in the guide. If you feel like there’s something you missed along the way, or if you need a refresher, you can always look back on earlier sections in the guide for assistance.

Please note that all modding will be done in Notepad++[notepad-plus-plus.org].

A1 – Starting clean / Important beginning information

So you’ve been playing reassembly, and you’re interested in modding. Great! Lets start with the basic preparations to streamline the modding process. The first thing we’ll do is setup the necessary elements for your mods so that the game can use them.

First we need to make a folder named “mods” In all lowercase, and it will be placed under /Saved games/Reassembly. After creating your mods folder, your directory should look like this:

Inside this folder is where all of your local mods will go. I’ll name my folder after the mod’s name, Rylor Knights. This mod will be released alongside this guide, hopefully this will help some budding modders learn to mod, or more experienced modders up their game.

Any faction mod requires at least four parts: A blocks.lua file, a factions.lua file, a regions.lua file, and a ship folder. They will look like this:

We’ll be writing these files soon, but all we need right now is a blocks.lua text file. To create it, make a new text document and rename it to blocks.lua. This can be opened in N++, regular notepad, and most text editors.

You can also use the json format for your mods, but for this guide I will be using the lua format.

Before we start writing blocks, we need to decide the numerical ID that our faction will have. Every faction has an id from 20-100, and a block ID range from 17,000 to 26,000. We’ll need to decide ours before we begin doing anything. I’ve chosen the faction ID 24, and the block ID range 24000-26000 for Rylor Knights. Now that that has been decided, we can begin writing our blocks file in the next section of the guide.

A2 – Writing your blocks.lua file / First hull block

In this section I’ll be going over how to structure your file, as well as a basic hull block. This is the way that I learned to write blocks.lua files, but you can do it a different way if you want to – provided the information stays the same.

(EDIT: To skip a line, it’s actually n not /n. I’m too lazy to remake the screenshot because the file was already deleted by now)

If you fill out the fields written in this template, you’ll have a basic hull block. I’ll fill in these fields now to demonstrate, and add some fields that a basic hull block will need.

Now that we’ve planned out what purpose we want this block to serve, we can begin to write its features. This block currently has no special features, default durability, default mass, and default price. Lets make it more durable, more dense, and free.

Now our block is twice as durable as terran hull, and four times as heavy. It’s also free, decided by the -1 point cost. Leaving the point cost at 0 will use the autoP generator to decide the price. In our case it would still be 0p, but I want to be sure.

Now for our colors! This hull will be a dark grey. Each block has 3 assignable colors – Fill color, Fill color 1, and Line color. If you specify 2 different fill colors, the block will pulse between the two over time. Setting them to the same color will nullify this effect. If you set all three colors to the same hex color, then the outline will be “invisible” as well. This is the effect I want to go for, so I’ll set all of my colors to the dark grey that I want.

(I’ve also removed the extra gaps since the descriptions are gone)

If you’d like your blocks to be unaffected by the campaign’s recolor system, you can add the NORECOLOR feature (I’ll go over adding features in the next section)

Now that we have our fill color, all we need to do now is decide how fast we want it to regenerate using growRate. The default grow rate is 20 for terrans, but since I want these to be very strong and slow, I’ll be making it 10.

Optionally, you can assign a block the NOREGEN feature if you’d like a block to be exclusive to a ship once, and only come back when creating a new ship/respawning. A similar feature to this is ONEUSE, which causes the block to self destruct when used, and then be regenerated as long as it doesn’t have the NOREGEN feature.

Congratulations! You now have a single hull block. In the next section we’ll be going over the Extends feature to create an array of hull shapes and sizes to use.

A3 – Adding a set of hull blocks as easy and as quickly as possible

In this section we’ll be adding a sizeable set of hull shapes, colors, and sizes for us to use. Previously you’d need to copy and paste your first block over and over, changing the size, color, and shape as needed. Nowadays, there is an even easier and faster way to make your hulls: Extends. Extends is a feature added in the last year or so that allows you to define one block to use as a template, and set the following blocks to copy the stats over from the template.

If you don’t understand extends, or just don’t want to bother with it, regular copy+pasting will work just as well.

This block, 24002, is extending off of 24001, copying its stats. The fields that we want to change are defined after the extends=. In this case we want a scale 2 square, so we add the scale= field and set it to 2. (The shape= field is only there for completion, so if you’re making more squares you don’t necessarily need it.)

Since you don’t need to write/copy the 10 extra lines, you can fit the entire extended block onto one line! This lets you visualize, copy, and edit your blocks much easier. Here are some of my extended blocks for Rylor Knights.

Here you can see I have several additional shapes and sizes. The first 3 are additional square sizes (shape 4000), while the last 8 are different rectangle block sizes (shape 4001). These extended blocks are also shrouded, which will be covered in a later section.

Protip: Hold ALT while in Notepad++ to select vertical columns! This works extremely well with extended arrays of hull blocks.

If you want more than one color/type of hull (This is highly recommended, but not required) Then it’s as easy as making a second template block and copying over your first set of extended blocks. From there you just hold ALT to select vertically, and change your template IDs. I usually change the hundreds place in the block IDs.

Something else to note: Make sure that you add a “1” and “2” to your hull’s names, or else they’ll scale with each other when using the < > keys in the constructor.

For example, lets say you want 17000 through 17100 to be one color of hulls, and 17101 through 17200 to be another color. You can copy the first set’s extends and modify the template ID to be 17100. Then you can change the hundreds place from a 0 to a 1 for the whole column. Pretty easy right? Block making is a breeze now with extends.

You can access your mod’s palette in the sandbox with the command ‘palette [faction ID]’. In order to build with them, you’ll need to press 3 first to enter construction mode, then you can start building with your blocks. For now, we’ll keep adding parts since we can’t make a functional ship yet. If you need to test your block’s colors, this can be done in the sandbox at any time. (This is highly advised considering reassembly brightens the colors a lot, and your colors might not be what you expect them to be).

If you make any changes to your blocks.lua and want to see them without restarting the game, you can use the command “reload” in the console to refresh your mods. From there you can clear the old palette and spawn in a new one.

I’m going to add many more hull pieces in different colors next using the same method as before, copying and pasting the hulls and changing the ID and shape.

A4 – Command + Utility blocks

The next step towards making a functional faction is a command. Every ship needs one (and only one) command block. Our command block will be the same color and density as our hull, but it’s gonna need some features. Lets add some:

Now our command block has the COMMAND feature. Now, you could technically be done here, but since we want our command to allow the ship to regenerate and have a tractor for resources, lets add those now.

The last thing to do is specify how far our tractor’s range should be. Assembler doesn’t need any specific fields.

Alright, now our command is up to par. This will suit any faction just fine, but some other optional features a command might want to have are:

• TORQUER – This helps the ship turn without thrusters. I almost always put a torquer on my commands, but it’s not necessary. You can add torque with the field torquerTorque=.
• GENERATOR – A command can include a generator if you want a very small starting ship with light weapons, and no dedicated generator. The fields required are generatorCapacityPerSec= and powerCapacity=.
• PHOTOSYNTH – This one helps generate resources early game if your faction is based on that sort of thing. You probably don’t want too much, no more than a photosynthPerSec= of 0.5.
• This isn’t a feature, but adding extra resource capacity to your command would help early game as well. This can be done with capacity=.

Now our command has everything you would want. Time to move on to utility blocks. These should be easy to make since I’ve already described the features and fields needed to make them above. I’ll write up a few examples here of a harvester block, a generator, and a solar panel:

One important thing to note: On the solar panel, I used a capacity of 0.00001 instead of 0, because writing just 0 would use the game’s default value. I don’t want my solar panels to be capable of storing resources, so using an extremely low decimal will round down to 0. (The -1 trick we used earlier for the points cost is exclusive to points, so for anything else you want to be 0 you can use a low decimal like this one).

I decided not to include a factory in the example, but they’re as simple as adding the FACTORY feature to any block. It has no included block fields, so the feature’s all you need.

Now you have your command, and some helpful utility blocks. Next we need some thrusters to get our hull chunks moving. Thrusters are simple to write, but can be balanced in several ways. I’ll include a few different types for demonstration purposes.

The first thruster is a general purpose thruster for small/medium ships. It has no special features. The second thruster is a very large capital thruster, with a heavy weight and large size. This prevents them from being used on smaller ships. It has a 1 second delay before operating as well, making them less effective at turning.

A5 – The Wide World of Cannons

Designing weapons in reassembly can be a lot of fun, especially if you have many creative ideas at hand. But since this section is introductory, I won’t be covering fancy cannons in depth. This will be covered later on if you’re interested. For now we’ll have 1-2 fragment stages at most, nothing too complicated.

I’ll be writing an example cannon, and explain each field’s purpose.

Cannons can have different setting for their explosions. They are as follows:

• ENABLED – This simply makes your cannon explode when hitting its target.
• FINAL – This makes your cannon explosive when hitting its target AND when the bullet reaches its maximum range.
• PROXIMITY – This option makes bullets explode when a target is within it’s blast radius.
• FRAG_IMPACT – The next three options only affect fragments. They can also be used alongside other options, similar to regular features. This option makes your fragment only occur when hitting a target, and not also when reaching maximum range (The default)
• FRAG_FINAL – This option makes your fragments only occur when reaching maximum range, and not when hitting a target.
• FRAG_PROXIMITY – This causes the projectile to fragment when a target is within the explosion radius.
• FRAG_NOFLASH – This option just removes the explosion “poof” from the fragmentation. It doesn’t remove all particles, however. Purely cosmetic.

WARNING: Reassembly’s explosive visual is smaller than the actual explosion’s radius, so if you need to achieve a specific radius it’s highly recommended you do some testing in the sandbox.

Cannons can use cannon boosters to add modular buffs and/or nerfs. These can be very potent, but unless they’re VERY carefully balanced they can end up being really strong really fast. Modular cannons are made using cannon boosters with different linear and/or exponential stat changes. Here is an example of all the possible stats you can adjust, with no changes made:

Now we can adjust out booster however we want. I’ll make a booster that increases damage, but reduces firing speed and increases energy cost.

Now you can make modular cannons!

Now that you know what kinds of things your cannon can include, you can make something useful out of it. Mixing and matching statistic imbalances can lead to more interesting weapon designs. Such as:

• Blasters – Good damage, fast fire rate, but low range and taxing energy consumption.
• Snipers – Very high damage, slower fire rate, very high velocity, energy cost and range.
• Shotguns – Low damage per bullet, but fires a large number of bullets in a short ranged burst.
• Point Defense – Usually a very fast bullet velocity, low damage and range. Typically assigned automatically to point defense to shoot down missiles and drones.
• Flak – Fires a powerful shell that splits into a large number of fragments.
• Artillery – Typically long ranged and slow firing like a sniper, but with lower velocity and some area damage
• Mortars – Shorter ranged artillery with higher damage and area of effect.

These are a few of the classic weapon “Archetypes” that you can find in many mods and games in general. They can all be achieved by changing stats in your cannon to get the desired strength. It’s all up to the mod maker’s creativity to use these ideas.

To bind a weapon automatically to a specific mouse button, add a field to your block as follows:
bindingId=n. N decides which mouse button/function the weapon is assigned to. This also works with lasers and launchers. Numbers 0-4 are valid. 0 being left mouse, 1 being right mouse, 2 being middle mouse. 4 and 5 are point defense and autofire respectively. (Autofire simply aims and fires automatically at your target as long as you are clicking one of the mouse buttons.)

Next step:

Yes, the dreaded fragments section. Fragment cannons can be wildly complex, or simple, both to varying effect. A complex fragment array doesn’t always make a gun more enjoyable to use/play against. Sometimes a couple of fragments is all you need!

Here’s an example of a basic mortar that releases fragments when it explodes:

The easiest way to think about fragments is like a chain reaction. A leads to B, which leads to C, etc where A, B, and C are fragment stages. When a fragment reaches it’s maximum range or hits a target, it will chain into the next defined fragment stage (or just stop if it’s the last fragment).

It’s important to note that fragments do not need the following fields (Only the main bullet needs these)

• roundsPerSec
• power
• recoil
• burstyness

Fragments can use the spread field to determine where to travel after fragmenting besides just straight forward. In order to do particularly fancy fragments, you’ll need to use spread patterns. There are 4 patterns as follows:

• RANDOM –This is the default spread behavior, choosing a random angle in the specified arc.
• CONSTANT –This chooses the absolute farthest the angle can go, as defined. By default it goes to the right, and negative numbers go to the left.
• SPIRAL –This will evenly distribute your bullets’ spread within the arc.
• ABSOLUTE –This option prevents the fragment from inheriting the parent bullet’s velocity and direction. The velocity and direction are instead decided by the set velocity/spread only.
• WAVE –This uses a sine wave to distribute the bullets. Some interactions can be unpredictable, so this is only used in niche situations.

Using these patterns to your best knowledge can allow for very intricate and magnificent fragment weapons.

A6 – Lasers and their complications

Lasers are completely different functionally compared to cannons, so they’ll need their own explanation.

Lasers can use bindings and turrets exactly the same as cannons. Lasers with multiple barrels defined will only fire out of the first barrel, unless it’s a charging laser. Charging lasers will cycle through the barrels.

Hybrid weapons are any combination of a laser, and cannon, and a launcher. These will all function individually at the same time while the bound button is pressed. The AI don’t use these particularly well, so keep that in mind.

A7 – Launchables (Missiles, Drones, and Mines)

Launchable weapons include missiles, drones, mines, and blueprint drones. All of these are decided by the features assigned to the launched block. Writing launchables is as easy as writing a regular block inside another block. Here is an example of a launcher without the missile being defined:

This will generate a launcher block that currently launches nothing. I will now fill in the launchable block with generic stats:

Here I’ve filled in the basic fields of any block, such as name, fields, color, durability, etc. The features I used allow the missile to have default behavior. Here is what each field does, and their significance:

• THRUSTER and TORQUER allows your launchable to accelerate and turn respectively.
• COMMAND Allows your launchable to aim and utilize the thruster and torquer features.
• EXPLODE signifies that this launchable is a missile, and enables the missile AI as well as the respective explosive fields.
• FREERES is a feature that can be put on any block. What it does is it prevents the block from dropping any resources when it ungrows.

These fields at the bottom of the block define how the launcher should grow and launch the launchable block:

• replicateTime is the time in seconds that it takes to grow a single launchable.
• launcherPower is the amount of power required to grow a single launchable.
• launcherOutSpeed is the speed at which the launchable is launched. You can use this to give missiles a quick launch, to fire mines farther away from your ship, etc.
• launcherAngVel allows your missile to spin a certain amount when it’s launched. Not many people use this since it can be strange and unpredictable with basic launchers, therefore it’s not included in this example.

Now we have a basic missile launcher! This fires missiles at a speed of 2 per second, they deal 30 damage with an explosion radius of 25.

Launchables don’t always have to be missiles. The type of launchable is defined by the features assigned to it.

• Missiles use EXPLODE, TORQUER, THRUSTER, and COMMAND. Torpedoes can be made by removing the TORQUER feature.
• Drones are made using COMMAND, TORQUER, THRUSTER, and any weapon such as a cannon, laser, or even another launcher.
• Mines are made using EXPLODE. This is all that’s required, but you can also add weapons or other features.
• Blueprint drones are advanced drones that use blueprints to grow into larger ships. The launchable is defined as the command block of the blueprint drone. Blueprint drones will be covered in more depth later in the guide.

Here is an example of a mine layer:

Now you know how to make launchers! Launchers are very versatile weapons that can add a lot of flavor to your mod.

A8 – Shields

Shields are fairly simple blocks. They generate a force field that absorbs projectile and laser damage up to a certain threshold. They have a regeneration time once they break, and can consume power to regenerate while active. Lets start with an example of a basic shield:

Shields can vary wildly in their statistics, providing strategic imbalances. You can make shields designed for defense with high health but low regeneration. Shields designed for offense can have higher regeneration and a lower delay, but high power consumption and average strength. It’s all up to you.

A9 – Activateable blocks

Activateable blocks are utility blocks that operate when a hotkey is held down. These can be used to make afterburners, decouplers, burst shields, and more. This function is applied to a block with the feature ACTIVATE. Along with this, a field named activatePower is used. This is the power consumed per second to operate the activated block.

Currently, ACTIVATE only works with the following features:

• THRUSTER
• SHIELD
• EXPLODE (Explodes when the keybind is pressed)
• ASSEMBLER
• PHOTOSYNTH
• GENERATOR
• FIN

WARNING: An activateable block with a high power consumption will still work even if the energy requirement isn’t met. Basically instead of waiting for the ship to have the required energy cost, instead the block removes that much energy from the available pool. It doesn’t actually check to make sure you have enough, so take that into account when making activate blocks.

A10 – Factions.lua and Regions.lua

A talented modder Ikswa has made a guide for writing a regions file, it should have everything you need.
His guide can be found here: [link]

B1 – Balancing Armor + Utilities

B2 – Balancing Cannons

B3 – Balancing Lasers

B4 – Balancing Launchables

C1 – Advanced Fragments

C2 – A Brief Coverage of Custom Shapes

C3 – Making Shrouds

References

Here is an image of every shape in the vanilla game:

Here is a link to my shape modding guide.

Here is every block feature in the current version of the game:

• None/empty [Hull blocks]
  -Block fields: name, blurb, group, shape, scale, durability, health, density, mass, growRate, armor, lifetime, points, fillColor, fillColor1, lineColor, capacity
• ACTIVATE
  This block is activated with a utility hotkey. Only works with these features: SHIELD, THRUSTER, ASSEMBLER, TRACTOR, PHOTOSYNTH. (TELEPORTER is activate by default)
  -Block fields: activatePower=
• ALWAYSFIRE
  The weapon will constantly fire, even when in the editor. Mostly used cosmetically
  -Block fields: None.
• ASSEMBLER
  This allows your ship to regenerate missing blocks and collect missing blocks from around it
  -Block fields: None.
• AUTOFIRE
  Automatically assigns this weapon to point defense.
  -Block fields: None.
• BUMPER
  This block doesn’t take collision damage. Very useful for tougher armor.
  -Block fields: None.
• CANNON
  Self Explanatory
  -Block fields: cannon={ }
• CANNON_BOOST
  Boosts specific fields for a cannon block.
  -Block fields: cannonBoost={ }
• CHARGING
  Allows the cannon/laser to charge up before firing, requiring the mouse button to be held down
  -Block fields: chargeMaxTime=, chargeMin=
• COMMAND
  Designates this block to being the command of the ship. Having more than 1 is not recommended
  -Block fields: command={ }
• DEACTIVATES
  The block deactivates instead of being destroyed (making it invincible and useless.) NOT RECOMMENDED.
• ENVIRONMENTAL
  Allows seeds to plant themselves on this block
• EXPLODE
  This block explodes upon contact with a non-friendly block
  -Block fields: explodeRadius=, explodeDamage=
• FACTORY
  Allows ship cores to be grown from this block on all ports.
• FREERES
  This block doesn’t drop resources when destroyed or when its lifetime expires. Necessary for missiles, drones, and other misc launchables with the COMMAND feature.
• GENERATOR
  Generates or consumes power at a constant rate.
  -Block fields: generatorCapacityPerSec=, powerCapacity=
• INTLINES
  Draws cosmetic lines between this block and surrounding blocks. Many blocks do this by default, this feature is useful for specific cosmetic hulls.
• INVISIBLE
  This hides the block’s rendering, but ports , barrels, icons, and shrouds still appear.
• INVULNERABLE
  Self explanatory. NOT RECOMMENDED.
• LASER
  Adds a laser weapon to the block.
  -Block fields: laser={ }
• LAUNCHER
  Launches a defined block such as a missile, a torpedo, a drone, etc. Can also be used with NEVERFIRE for growing cosmetic mines that do nothing but add decorations.
  -Block fields: replicateBlock={}, replicateTime=, launcherPower=, launcherOutSpeed=, launcherAngVel=
• LAUNCHER_BARRAGE
  Launches all built missiles simultaneously instead of as soon as possible.
  -Block fields: None.
• MELEE
  Does extra damage upon contact. NOT RECOMMENDED (It’s either very overpowered or useless, no real median. If you really want melee, go for it, but it’s op.)
  -Block fields: meleeDamage=
• NEVERFIRE
  The weapon or launcher will never fire and does not have a keybind.
  -Block fields: None.
• NOICON
  This removes the symbol(s) on the block. It will appear like regular hull. Does not affect shrouds.
  -Block fields: None.
• NOCLIP
  Does not collide with anything.
  -Block fields: None.
• NOCLIP_ALLY
  Does not collide with your own ships.
  -Block fields: None.
• NOPALETTE
  Doesn’t appear in the campaign palette. Useful for testing blocks, blueprint drone pieces, etc
  -Block fields: None.
• NOREGEN
  Does not regenerate or grow back.
  -Block fields: None.
• NORECOLOR
  This block doesn’t recolor in campaign. Useful for specific cosmetic purposes.
  -Block fields: None.
• ONEUSE
  After firing/launching/etc the block self destructs. It can be grown back again.
  -Block fields: None.
• PALETTE
  Adds this block to the campaign palette even if it’s not used on any ships. I suggest you put this on every block you intend on being used in the campaign.
  -Block fields: None.
• PHOTOSYNTH
  Generates or consumes resources over time. Works with ACTIVATE.
  -Block fields: photosynthPerSec=
• REGROWER
  Allows the ship to regenerate but not collect debris (Currently broken in the current version of the game as of writing this. I’ll remove this if it gets fixed.)
  -Block fields: None.
• ROOT
  Acts as a root block for plants and structures.
  -Block fields: None.
• SEED
  Acts as a seed for plantable launched seeds.
  -Block fields: seedLifetime=, launchSpeed=, launchCapacity=, launchLifetime=, launchResources=
• SELFFACTORY
  Allows the ship to duplicate itself, but no other designs. NOT RECOMMENDED FOR GENERAL PURPOSES.
  -Block fields: None.
• SHIELD
  Adds a shield to the block.
  -Block fields: shield={ }
• TELEPORTER
  Allows your ship to teleport with a utility hotkey
  -Block fields: teleporterRadius=, teleporterPower=
• TELESPAWN
  Spawns ships instantly for the full price. NOT RECOMMENDED.
  -Block fields: None.
• THRUSTER
  Adds a thruster to the block.
  -Block fields: thrusterForce=, thrusterBoost=, thrusterBoostTime=, thrusterColor=, thrusterColor1=
• TORQUER
  Allows the ship to turn faster around the center of mass, but does not provide any thrust.
  -Block fields: torquerTorque=
• TRACTOR
  Allows the ship to pick up R packets and debris to use, almost unplayable without one of these.
  -Block fields: tractorRange=
• TURRET
  Allows a laser/cannon to aim at a certain speed. Can be limited to create gimbal turrets, broadside guns, etc
  -Block fields: turretSpeed=, turretLimit=, barrelCount=, barrelSize=