Zero-K - User contributions [en]

Transportation

2024-07-28T21:55:32Z

Sprung:

Transports are used to rapidly move ground and sea forces around the battlefield. There are two transports: [[Charon]] and [[Hercules]]. Both are constructed at the [[Gunship Plant]].

[[Teleportation]] is an alternative means of transportation.

== Basic Commands and Abilities ==

=== Mass and Capacity ===
Transports can pick up and carry a single unit at a time.

[[Charon]] can carry '''light''' and '''medium''' units while [[Hercules]] can carry any transportable unit. Transports cannot carry air units. A unit's transportability depends on its metal cost. Light units are units below or equal to 500 metal, medium units are between 501 and 1000 metal, and heavy units are everything else. A unit's transportability and mass can be viewed in an information window by {{key press|Space}}-clicking on the unit.

Laden transports have a speed penalty depending on the mass of their cargo. Transports receive no additional speed penalty for transporting units up to their own mass, otherwise, they have a speed modifier of {{frac|2 × <var>selfMass</var>|{{expr|<var>selfMass</var> + <var>cargoMass</var>}}}}.

=== Loading ===
Transports can pick up any valid stationary unit, including stunned enemies. They have to physically lower themselves onto a unit to pick it up. This process can take a few seconds, depending on the target. There are two ways to load units:
# Issue the [[Load Command|'''Load''']] command (hotkey {{key press|L}}) to a transport to load the target unit. This command is generally available as a right-click context command. Issue an area command with by clicking and dragging to tell multiple transports to load a group of units.
# Select a mixed selection of transports and ground units and issue the '''Load Selected Units''' command (double-tap {{key press|L}}) to have the transports load the selected units. Idle units will be loaded into the transports while units with orders will be loaded and transported to the end of their order queue.

=== Unloading ===
Transports can either carefully place their cargo on the ground, or they can eject it in-flight.
* Use the [[Unload Command|'''Unload''']] command (hotkey {{key press|U}}) to unload carefully. This command can be issued in an area selected by clicking and dragging or along a line by {{key press|Alt}}-clicking and dragging.
* Use the [[Eject Cargo Command|'''Eject Cargo''']] command (hotkey {{key press|D}}) to drop transported units. This may damage the dropped units. Transports carrying bombs draw a target where the bomb is going to hit on the ground based on their velocity.

== Transport AI ==
'''Transport AI''' can be toggled with the unit AI state toggle (<img src="//raw.githubusercontent.com/ZeroK-RTS/Zero-K/master/LuaUI/Images/commands/states/bulb_on.png" height="18">) on transports.

Transports can be set to [[Guard Command|guard]] a factory to automatically pick up newly created units and drop them off at the end of the rally queue.

There are two queueable commands: ''Embark'' [[File:Embark.png|18px]] and ''Disembark'' [[File:Disembark.png|18px]]—these commands appear on transportable land units and factories when you build your first air transport.
*'''Embark'''—wait for transport to pick me up. Transports called by the ''Embark'' command will return to the spot where they took the unit using the same path.
*'''Disembark'''—safely exit and from the transport.

=== Benefit ===
A transport might skip some units because it finds it pointless to transport them. It takes several things into account—distance of transport from unit, planned unit path, unit speed, transport speed, transport land times, terrain height differences—all of this is used to estimate the "benefit" of transporting a given unit with the air transport.

'''Benefit''' is the number of seconds saved by using a transport. It transports units only if benefit is greater than five seconds and in the order of benefit (slowest units will be transported first, fast units might be ignored completely). The exception to this is the ''Embark'' command, which serves as "priority" transport—units waiting with the ''Embark'' command will be served first.

=== Possible uses ===
# Give bot factory waypoints through safe area next to the current battlefield.
#* Result: Units walk along these waypoints and if there are idle transports they will pick them up and transport them to their destination.
# Give factory waypoint to ally's base entrance followed by [[Patrol Command|patrol]].
#* Result: Units walk there and if transport nearby it will pick it up, drop it off and the unit will start patrolling.
# Give factory a move order near your base, ''Embark'', then move to an impassable mountain.
#* Result: Units will emerge from factory and enter ''Embark'' mode—they will stand there and wait for transport to get them to the mountain.
# Select crawling bombs, click to move to enemy base then click ''Embark''.
#* Result: Bombs will stop and wait for transports, transports will carry them to enemy base.
# Select Dantes, give them move commands across air safe areas, followed by disembark from behind the base spot and move to enemy base. Then click ''Embark''.
#* Result: Dantes will stop and wait for transports. Transport will carry them along the waypoints to back of enemy base, unload them. From there, Dantes will continue on foot.

== Ferry routes ==
Ferry routes automate transports to travel units across a set path to a destination. The <abbr title="user interface">UI</abbr> for creating ferry routes is (by default) in the upper left corner bar next to ''retreat and repair''. The symbol is a red circle with a ray pointing out of it to the right ([[File:Ferry.png|18px]]). To create a ferry route, first left-click the ferry route button, next left-click the start location of your ferry route, then left-click the destination. A ferry route does not have to be just a straight line. The path to take can twist and turn all you like by holding {{key press|Shift}} and left-clicking between the starting area and destination. Your ferry route will appear as a hard red circle indicating the start and a line directing out of that circle towards the destination.

Transports return to the spot where they took a unit using the same path.

<htmltag tagname="video" width="560" height="320" loop="true" autoplay="true" src="//i.imgur.com/XHY0vP7.mp4" controls="true"></htmltag>

You can even edit your ferry route by clicking the ferry route button, holding {{key press|Shift}} and clicking where you placed a start, end, or corner to select it, and then clicking where you want that point to be.

<htmltag tagname="video" width="560" height="320" loop="true" autoplay="true" src="//i.imgur.com/WC2qb03.mp4" controls="true"></htmltag>

To remove a ferry route, click the ferry route button and left-click a start location.

<htmltag tagname="video" width="560" height="320" loop="true" autoplay="true" src="//i.imgur.com/SHFhe68.mp4" controls="true"></htmltag>

Now that you have your ferry route, it's time to put it to use! Assign transports to the ferry route by issuing a move command into the start circle. The transports will now stay within a short distance of the start, even if you try and move them away, waiting for units. Take a unit you want to ferry and issue a move order into the circle. Once the unit is in the circle, it will wait for a transport to pick it up and move it to the end of the ferry route. You can shift queue commands for the unit, and it will follow the commands after arrival at the destination.

<htmltag tagname="video" width="560" height="320" loop="true" autoplay="true" src="//i.imgur.com/No0wGkg.mp4" controls="true"></htmltag>

Potential uses for ferry routes:
*To move a large army around static anti-air cover to far locations, as the transports will follow the route both to and from the location.
*You can set your factory's waypoint to the ferry route start, and units will wait for transports to ferry them.

While automated, ferry routes require periodical check-ups. Under certain circumstances, a unit may end up waiting to be transported forever. Also, units waiting for transports may enter the [[Wait Command|Wait]] state, denoted by an hourglass icon above the unit, which will prevent them from defending themselves.



{{Navbox manual}}

Modelling guidelines

2024-06-15T12:33:42Z

Sprung: Example for a remodel PR

== Before you get started ==
* keep in mind that someone else might already be working on the unit you were planning to remodel, so check [https://docs.google.com/spreadsheets/d/11UyxUYvkbwck0F2cEVEdHvxxtllXzOBDkXnOtb-4fK8/edit#gid=126218909 the remodel tracker]. We also accept "loose" models (i.e. not remodels of existing units) but by default these will just join a sort of unused model pool for use by modders or experiments.
* be aware that devs are handling other stuff and are not artists at heart so your model may get "difficult" feedback and it may take a while to implement it ([https://github.com/ZeroK-RTS/Zero-K/pull/5164 here]'s an example process for a recent model, as a reference). Don't get discouraged!
* be aware that implementing a model into the game takes some knowledge of the game engine, so realistically you will require help at some point. Don't be afraid to ask!

== Preparation ==
Here's a bunch of things to think about and take into account when laying the foundations for your model.

* let people know you're starting work to get initial feedback (#modelling channel on ZK Discord).
* if you're doing a remodel, the existing model is your authoritative source of concept art. Identify what makes it unique and replicate it. An ideal remodel is merely a strict quality upgrade.
* a thing to watch out is whether the unit can fire "over itself", i.e. another unit of the same type. If the original unit blocks itself from firing then this should carry over to a remodel.
* the model should generally not have any bits sticking out too much since they will clip into adjacent things. A good model can fit "neatly" inside a sphere or a box.
* the model should be split into separate pieces, which double as the 'bones' of the model (skinning is supported with up to 4 pieces/bones per vertex though). More technical info at [[Blender_To_Zero-K|the more technical modelling guide for Blender]].
* use the existing model as a reference for the order of magnitude when it comes to polygons, perhaps check some similar units from the same unit class (there's [https://github.com/ZeroK-RTS/Zero-K/issues/5214 a ticket aiming to produce a full listing], maybe it will contain something interesting by the time you read it). As a ballpark you can get into thousands unless the unit is particularly spammable (say Flea).
* keep the texture on the smaller side (say 512 or 1024 unless it's a rare unit), again check the ticket above or look at similar units. If you plan to remodel a handful of similar units it is an excellent idea to use a shared texture (atlas) between them, which gives benefits in visual consistency and rendering performance and is a good reason to make the texture much larger.

== During work; initial feedback ==
This is the stage where the basic model shape is done and you want to move onto the details.

* double-check that there is a materials texture (second texture whcih defines shininess etc) and also a normals texture (FIXME normals may currently be broken)
* feedback, and eventually model approval, comes from GoogleFrog. Show him (and perhaps the general modelling community at #modelling) some screenshots or a video, the earlier you do so the more chance of finding potential problems. GoogleFrog is the lead dev/designer and is quite busy with other stuff so it may take him a while to give feedback.
* if GF initially has negative feedback you can talk to Niarteloc for a quicker response.

== Model has taken up shape ==
* at this point, getting feedback involves a proof-of-concept implementation of the model ingame that GoogleFrog could test.
* salient places on the model (e.g. tip of the barrel where projectiles will appear) will need an empty piece with no geometry and just the "origin" set to their location.
* the model needs a basic animation at this point but unfortunately this involves Lua code. Look at existing scripts to get a basic idea. Otherwise it should largely be a matter of placing files in the directory structure correctly.
* if you're willing to do this on your own, check out these: (FIXME add links some example accepted PRs, maybe a scripting guide or something)
* eye candy (special effects, fancy animations etc) are optional at this point (but of course if you manage to implement them that's great).
* talk to Niarteloc or Sprung if you struggle with this step.

== After the base model is done ==
* check with GoogleFrog again to make sure it's really ready.
* there needs to be a wreck model. It is a mangled version of the base mesh, and there's a standard texture for wrecks so you don't need to provide one (but are welcome to if it makes the wreck look much better, just keep the color tone the same as default).
* remaining salient places, e.g. eye candy particle spawners (tips of aircraft wings for blinking lights, underside of tank treads for dust kickup etc) need an empty piece as well, if you haven't added them in earlier stages.
* playtesting the model would be great. Play a game vs bots using the model (FIXME link a basic modding guide here)

Status Effects

2024-04-13T14:20:21Z

Sprung: Reef now captures.

Zero-K has a lot of status effects, special debuffs that can be applied to enemy units to help suppress them and support your armies in battle. They work by filling separate damage meters underneath the target's hit points, and generate various effects.{{TOC right}}

== EMP damage ==
<abbr title="electromagnetic pulse">EMP</abbr> damage stuns enemies, completely disabling them and preventing them from moving, using abilities, or returning fire.

[[File:Weapon EMP.jpg]]

* When an instance of EMP damage is applied to an enemy, it is checked in proportion to the enemy's current health and converted into a stacking percentage.
* When EMP percentage reaches 100% or higher, the unit is stunned.
* EMP percentage on units decay at a rate of 2.5% per second. The moment the unit's percentage drops below 100%, it is no longer stunned.
* Even though EMP percentage stacks, it doesn't stack freely: every EMP weapon has a maximum percentage it can raise a unit to. This is described in the weapon stat block as a maximum stun time - each second effectively being a 2.5% maximum over 100% since EMP decays at that rate.
** For example, a [[Venom]] has a maximum stun time of 1s, which means it can at most raise an enemy's stun percentage to 102.5%.
** Meanwhile a [[Widow]] can stun a unit for 30s, which means it can raise an enemy's stun percentage to 100 + 30 × 2.5 = 175%.

Against shields, EMP damage is divided by 3 and converted into normal shield damage. If a weapon deals normal and EMP damage together, the EMP damage is applied last.

EMP is yellow, or in the case of the self-destructing [[Imp]], blue.

== Disarm damage ==
Disarm is a particular type of EMP that will leave the afflicted units able to move, but unable to use any weapons or special abilities (this includes jumping, using build power, regeneration or receiving income from the commander's Vanguard economy module). Disarm damage is converted into a separate disarm percentage bar tracked independently from EMP percentage. Disarmed units flash yellow instead of blue.

== Slow damage ==
Slow damage gradually decreases the movement speed and rate of fire of enemy units.

[[File: Weapon slow.jpg]]

* Unlike EMP or disarm damage, slow damage is tracked and stored directly on the affected unit as a total rather than being converted into a percentage.
* As long as a unit has slow damage on it, it is slowed in proportion to the slow damage / its current health. This means that damaging a unit can increase its slow since the slow damage buffer becomes proportionally larger.
* Slow damage is always capped at 50% of the unit's current health. If a unit is damaged to the point that slow damage would rise over this limit, the extra slow damage is cleared.
* After 0.5s of taking no slow damage, units start clearing slow damage = 4% of their current health per second.
* Some units (the [[Limpet]] and [[Moderator]]) apply '''overslow''':
** This is a secondary status effect that raises the slow damage cap of the target to higher than 50% of the target's current HP.
** Even when a unit's slow damage taken is higher than 50% of its current health, it is still only slowed down by 50%. Overslow effectively "stretches out" the 50% slow longer.
** Overslow is tracked and cleared separately from slow.

Like EMP damage, slow damage is divided by 3 and converted into normal damage against shields.

Slow is purple.

== Capture damage ==
Capture damage is a special kind of damage only dealt by the [[Dominatrix]] and the [[Reef]]'s drones. It can steal a unit from an enemy and place it under your (potentially permanent) control.

* When an instance of capture damage is applied to an enemy, it is directly converted into a percentage just like with EMP damage. Unlike with EMP damage, it's divided by (the target enemy's current HP + 500) instead of just the target's current HP.
* When a unit reaches 100% capture percentage, it is captured and belongs to the unit who dealt that last bit of capture damage. It stays this way until the controller is destroyed.
* After 5s of taking no capture damage, capture percentage decays at a rate of 4% per second.
* If a captured unit's controller is destroyed, it is returned to its original owner with 95% capture percentage.
* Capturing a controller grants control of all its subordinates, in a tree-like control structure.
* Even though capture percentage stacks, it does not stack between players who belong on different teams. Each team gets their own capture bar for the target unit, and the UI will only display the highest percentage.

When a capturing unit takes control of an enemy unit, a visible control line is drawn leading from the controller to its victim. The full line is visible to any enemy player who has vision of either end of the line, so they can spot hidden controllers.

Even though the Dominatrix has a 12 second reload time after capturing a unit, this only applies to the Dominatrix that dealt the final instance of capture damage - every other Dominatrix that contributed can fire on new targets immediately. Reef's drones have individual capture reload timers but their damage counts for the Reef.

Capturing a unit that originally belonged to an ally returns it to that ally without creating a control link.

{{Navbox manual}}

Modelling guidelines

2024-03-23T18:19:56Z

Sprung: Technical limits

== Before you get started ==
* keep in mind that someone else might already be working on the unit you were planning to remodel, so check [https://docs.google.com/spreadsheets/d/11UyxUYvkbwck0F2cEVEdHvxxtllXzOBDkXnOtb-4fK8/edit#gid=126218909 the remodel tracker]. We also accept "loose" models (i.e. not remodels of existing units) but by default these will just join a sort of unused model pool for use by modders or experiments.
* be aware that devs are handling other stuff and are not artists at heart so your model may get "difficult" feedback and it may take a while to implement it. Don't get discouraged!
* be aware that implementing a model into the game takes some knowledge of the game engine, so realistically you will require help at some point. Don't be afraid to ask!

== Preparation ==
Here's a bunch of things to think about and take into account when laying the foundations for your model.

* let people know you're starting work to get initial feedback (#modelling channel on ZK Discord).
* if you're doing a remodel, the existing model is your authoritative source of concept art. Identify what makes it unique and replicate it. An ideal remodel is merely a strict quality upgrade.
* a thing to watch out is whether the unit can fire "over itself", i.e. another unit of the same type. If the original unit blocks itself from firing then this should carry over to a remodel.
* the model should generally not have any bits sticking out too much since they will clip into adjacent things. A good model can fit "neatly" inside a sphere or a box.
* the model should be split into separate pieces, which double as the 'bones' of the model (skinning is supported with up to 4 pieces/bones per vertex though). More technical info at [[Blender_To_Zero-K|the more technical modelling guide for Blender]].
* use the existing model as a reference for the order of magnitude when it comes to polygons, perhaps check some similar units from the same unit class (there's [https://github.com/ZeroK-RTS/Zero-K/issues/5214 a ticket aiming to produce a full listing], maybe it will contain something interesting by the time you read it). As a ballpark you can get into thousands unless the unit is particularly spammable (say Flea).
* keep the texture on the smaller side (say 512 or 1024 unless it's a rare unit), again check the ticket above or look at similar units. If you plan to remodel a handful of similar units it is an excellent idea to use a shared texture (atlas) between them, which gives benefits in visual consistency and rendering performance and is a good reason to make the texture much larger.

== During work; initial feedback ==
This is the stage where the basic model shape is done and you want to move onto the details.

* double-check that there is a materials texture (second texture whcih defines shininess etc) and also a normals texture (FIXME normals may currently be broken)
* feedback, and eventually model approval, comes from GoogleFrog. Show him (and perhaps the general modelling community at #modelling) some screenshots or a video, the earlier you do so the more chance of finding potential problems. GoogleFrog is the lead dev/designer and is quite busy with other stuff so it may take him a while to give feedback.
* if GF initially has negative feedback you can talk to Niarteloc for a quicker response.

== Model has taken up shape ==
* at this point, getting feedback involves a proof-of-concept implementation of the model ingame that GoogleFrog could test.
* salient places on the model (e.g. tip of the barrel where projectiles will appear) will need an empty piece with no geometry and just the "origin" set to their location.
* the model needs a basic animation at this point but unfortunately this involves Lua code. Look at existing scripts to get a basic idea. Otherwise it should largely be a matter of placing files in the directory structure correctly.
* if you're willing to do this on your own, check out these: (FIXME add links some example accepted PRs, maybe a scripting guide or something)
* eye candy (special effects, fancy animations etc) are optional at this point (but of course if you manage to implement them that's great).
* talk to Niarteloc or Sprung if you struggle with this step.

== After the base model is done ==
* check with GoogleFrog again to make sure it's really ready.
* there needs to be a wreck model. It is a mangled version of the base mesh, and there's a standard texture for wrecks so you don't need to provide one (but are welcome to if it makes the wreck look much better, just keep the color tone the same as default).
* remaining salient places, e.g. eye candy particle spawners (tips of aircraft wings for blinking lights, underside of tank treads for dust kickup etc) need an empty piece as well, if you haven't added them in earlier stages.
* playtesting the model would be great. Play a game vs bots using the model (FIXME link a basic modding guide here)

Modelling guidelines

2024-03-23T00:17:53Z

Sprung: Modelling guidelines by LKST

== Before you get started ==
* keep in mind that someone else might already be working on the unit you were planning to remodel, so check [https://docs.google.com/spreadsheets/d/11UyxUYvkbwck0F2cEVEdHvxxtllXzOBDkXnOtb-4fK8/edit#gid=126218909 the remodel tracker]. We also accept "loose" models (i.e. not remodels of existing units) but by default these will just join a sort of unused model pool for use by modders or experiments.
* be aware that devs are handling other stuff and are not artists at heart so your model may get "difficult" feedback and it may take a while to implement it. Don't get discouraged!
* be aware that implementing a model into the game takes some knowledge of the game engine, so realistically you will require help at some point. Don't be afraid to ask!

== Preparation ==
Here's a bunch of things to think about and take into account when laying the foundations for your model.

* let people know you're starting work to get initial feedback (#modelling channel on ZK Discord).
* if you're doing a remodel, the existing model is your authoritative source of concept art. Identify what makes it unique and replicate it. An ideal remodel is merely a strict quality upgrade.
* a thing to watch out is whether the unit can fire "over itself", i.e. another unit of the same type. If the original unit blocks itself from firing then this should carry over to a remodel.
* the model should generally not have any bits sticking out too much since they will clip into adjacent things. A good model can fit "neatly" inside a sphere or a box.
* the model should be split into separate pieces, which double as the 'bones' of the model (skinning is supported with up to 4 pieces/bones per vertex though). More technical info at [[Blender_To_Zero-K|the more technical modelling guide for Blender]].
* you can have quite a lot of polygons (Glaive is 1000+) but keep the texture on the smaller side. If you plan to remodel a handful of similar units it is an excellent idea to use a shared texture (atlas) between them, which gives benefits in visual consistency and rendering performance and is a good reason to make the texture a bit larger.

== During work; initial feedback ==
This is the stage where the basic model shape is done and you want to move onto the details.

* double-check that there is a materials texture (second texture whcih defines shininess etc) and also a normals texture (FIXME normals may currently be broken)
* feedback, and eventually model approval, comes from GoogleFrog. Show him (and perhaps the general modelling community at #modelling) some screenshots or a video, the earlier you do so the more chance of finding potential problems. GoogleFrog is the lead dev/designer and is quite busy with other stuff so it may take him a while to give feedback.
* if GF initially has negative feedback you can talk to Niarteloc for a quicker response.

== Model has taken up shape ==
* at this point, getting feedback involves a proof-of-concept implementation of the model ingame that GoogleFrog could test.
* salient places on the model (e.g. tip of the barrel where projectiles will appear) will need an empty piece with no geometry and just the "origin" set to their location.
* the model needs a basic animation at this point but unfortunately this involves Lua code. Look at existing scripts to get a basic idea. Otherwise it should largely be a matter of placing files in the directory structure correctly.
* if you're willing to do this on your own, check out these: (FIXME add links some example accepted PRs, maybe a scripting guide or something)
* eye candy (special effects, fancy animations etc) are optional at this point (but of course if you manage to implement them that's great).
* talk to Niarteloc or Sprung if you struggle with this step.

== After the base model is done ==
* check with GoogleFrog again to make sure it's really ready.
* there needs to be a wreck model. It is a mangled version of the base mesh, and there's a standard texture for wrecks so you don't need to provide one (but are welcome to if it makes the wreck look much better, just keep the color tone the same as default).
* remaining salient places, e.g. eye candy particle spawners (tips of aircraft wings for blinking lights, underside of tank treads for dust kickup etc) need an empty piece as well, if you haven't added them in earlier stages.
* playtesting the model would be great. Play a game vs bots using the model (FIXME link a basic modding guide here)

Quick Stat Tweaks

2023-12-21T01:48:15Z

Sprung: oops

The Tweak Units modoption can be used to modify many unit and weapon parameters. It can be used for rapidly testing balance changes or just for making a quick game mode. It has limitations and should not be used for large mod projects, see [[Mod Creation]] and [[How To Play Mods]] to get started on full modding.

[[File:Tweakunitsdefs.png]]

Stat tweaks can be saved and shared as a [[Custom Modes | Custom Mode]].

== Workflow ==
The Tweak Units modoption overwrites unit parameter (called unitDefs) as they are loaded. The modoption requires a base64-encoded Lua array of differences. Here is how to use it.
* Make a Lua table in an empty file.
* For each unit you wish to modify, add an empty table indexed by the [[Internal unit names|internal name]] of the unit to your table.
* Search for the units you wish to modify in the [https://github.com/ZeroK-RTS/Zero-K/blob/master/units Zero-K repository].
* Copy the parameters you wish to modify into the table, maintaining the structure of the unitDef table.
* [https://www.base64encode.org Base64 encode] your table.
* Put the base 64 encoding of your table into the Tweak Units modoption.
* Start the game.
* Check infolog.txt in your install directory and fix your syntax errors.

Check out the [https://springrts.com/wiki/Gamedev:UnitDefs unit def] and [https://springrts.com/wiki/Gamedev:WeaponDefs weapon def] pages on the SpringRTS wiki for definitions of many of the parameters. Search the Internet for tutorials on Lua tables.

== Limitations ==
Tweak Units cannot be used to change parameters that are part of a unit's animation, and access to some of the more unique abilities may be missing. In particular, the aiming speed of most units cannot be changed with this method.

== Simple Example ==
In this example we make Glaive faster and cheaper.

Start with an empty Lua table.
<syntaxhighlight lang="lua">{
}</syntaxhighlight>
A search through the [https://github.com/ZeroK-RTS/Zero-K/blob/master/units unitdef repository] reveals that Glaive is known as cloakraid internally. [https://github.com/ZeroK-RTS/Zero-K/blob/master/units/cloakraid.lua This] is the file. Add an empty table with key 'cloakraid'.
<syntaxhighlight lang="lua">{
cloakraid = {},
}</syntaxhighlight>
The [https://springrts.com/wiki/Gamedev:UnitDefs SpringRTS wiki page on unitdefs] says that a unit's cost is 'metalCost' and its speed is just 'speed'. [https://github.com/ZeroK-RTS/Zero-K/blob/master/units/cloakraid.lua The Glaive file] shows us the current value of these parameters, as well as their position in the structure of a unitdef. We can change these values like so:
<syntaxhighlight lang="lua">{
cloakraid = {
metalCost = 50,
speed = 240,
},
}</syntaxhighlight>
Copy this text into a [https://www.base64encode.org/ base64 encoder] and click encode. Here is the resulting encoding.
<code style="display:block;overflow:auto">ewogICAgY2xvYWtyYWlkID0gewogICAgICAgIG1ldGFsQ29zdCA9IDUwLAogICAgICAgIHNwZWVkID0gMjQwLAogICAgfSwKfQ==</code>
Set the Tweak Units modoption to your encoding and start the game. Your infolog should indicate that the modoption loaded successfully.
<samp><pre>[f=-000001] Loading UnitDefs_posts
[f=-000001] Loading tweakunits modoption <------
[f=-000001] Loading tweakunits for cloakraid <------
[f=-000001] Loading FeatureDefs_posts
[f=-000001] Loading WeaponDefs_posts
[f=-000001] Loading ArmorDefs_posts</pre></samp>

== Advanced Example ==
In this example we will change Bandit's damage and range, and add it to the Glaive changes.

As in the simple example, we find the [https://github.com/ZeroK-RTS/Zero-K/blob/master/units/shieldraid.lua Bandit's file] and see that it's called shieldraid. To change Bandit and Glaive at the same time, we add a new sub-table to the table from the previous example.
<syntaxhighlight lang="lua">{
cloakraid = {
metalCost = 50,
speed = 240,
},
shieldraid = {},
}</syntaxhighlight>
Weapon parameters can be found in the [https://springrts.com/wiki/Gamedev:WeaponDefs SpringRTS page on weapon defs], and Zero-K stores them as a sub-table within unitdefs. The range parameter is inside 'LASER' (the internal name of the Bandit's weapon), which is inside the weaponDefs table of Bandit. Weapon damage is further nested inside the damage sub-table of the weapondef.
<syntaxhighlight lang="lua">{
cloakraid = {
metalCost = 50,
speed = 240,
},
shieldraid = {
weaponDefs = {
LASER = {
range = 600,
damage = {
default = 50,
},
},
},
},
}</syntaxhighlight>
As before, we now take this text, [https://www.base64encode.org/ base64 encode] it, and copy it into Tweak Units. Encodings can be shortened by removing whitespace prior to encoding.
<code style="display:block;overflow:auto">e2Nsb2FrcmFpZD17bWV0YWxDb3N0PTUwLHNwZWVkPTI0MCx9LHNoaWVsZHJhaWQ9e3dlYXBvbkRlZnM9e0xBU0VSPXtyYW5nZT02MDAsZGFtYWdlPXtkZWZhdWx0PTUwLH0sfSx9LH0s</code>

== Mass post-processing ==

The above examples deal with specific values for a single unit (e.g. "make Glaive have 240 speed").
It is also possible to write Lua code that works on units, including changing values for all units or doing some sort of logic. This time, the option is not "Tweak Units" but "Tweak Defs". Again, it should be encoded to base64.

Here's an example:
<syntaxhighlight lang="lua">for name, ud in pairs(UnitDefs) do
if ud.speed then
ud.speed = ud.speed*10
else
ud.health = ud.health*5
end

if ud.metalcost then
ud.metalcost = ud.metalcost*2
end
end</syntaxhighlight>

UnitDefs is a Lua table indexed with unit names as above (for example "cloakraid" for Glaive) whose values are the unit def tables in a similar format as for tweakunits, BUT WITH ALL KEYS LOWERCASE (notice how it's metalcost and not metalCost!). This snippet increases unit speeds 10 times for all mobiles and health 5 times for all statics, and makes all units twice as expensive. Some fields may be <code>nil</code> (for another example, death explosions are weapons but don't have a reload time). Specific Tweak Units values override the values that result from Tweak Defs.

Happy hacking!

[[File:Zk_1_7_11_0_cover.jpg|frame|center]]

[[Category:Development]]{{Navbox manual}}

Quick Stat Tweaks

2023-12-21T01:47:14Z

Sprung: Change used def keys (maxdamage/maxvelocity are now speed/health, add metalCost to illustrate lowerkeys)

The Tweak Units modoption can be used to modify many unit and weapon parameters. It can be used for rapidly testing balance changes or just for making a quick game mode. It has limitations and should not be used for large mod projects, see [[Mod Creation]] and [[How To Play Mods]] to get started on full modding.

[[File:Tweakunitsdefs.png]]

Stat tweaks can be saved and shared as a [[Custom Modes | Custom Mode]].

== Workflow ==
The Tweak Units modoption overwrites unit parameter (called unitDefs) as they are loaded. The modoption requires a base64-encoded Lua array of differences. Here is how to use it.
* Make a Lua table in an empty file.
* For each unit you wish to modify, add an empty table indexed by the [[Internal unit names|internal name]] of the unit to your table.
* Search for the units you wish to modify in the [https://github.com/ZeroK-RTS/Zero-K/blob/master/units Zero-K repository].
* Copy the parameters you wish to modify into the table, maintaining the structure of the unitDef table.
* [https://www.base64encode.org Base64 encode] your table.
* Put the base 64 encoding of your table into the Tweak Units modoption.
* Start the game.
* Check infolog.txt in your install directory and fix your syntax errors.

Check out the [https://springrts.com/wiki/Gamedev:UnitDefs unit def] and [https://springrts.com/wiki/Gamedev:WeaponDefs weapon def] pages on the SpringRTS wiki for definitions of many of the parameters. Search the Internet for tutorials on Lua tables.

== Limitations ==
Tweak Units cannot be used to change parameters that are part of a unit's animation, and access to some of the more unique abilities may be missing. In particular, the aiming speed of most units cannot be changed with this method.

== Simple Example ==
In this example we make Glaive faster and cheaper.

Start with an empty Lua table.
<syntaxhighlight lang="lua">{
}</syntaxhighlight>
A search through the [https://github.com/ZeroK-RTS/Zero-K/blob/master/units unitdef repository] reveals that Glaive is known as cloakraid internally. [https://github.com/ZeroK-RTS/Zero-K/blob/master/units/cloakraid.lua This] is the file. Add an empty table with key 'cloakraid'.
<syntaxhighlight lang="lua">{
cloakraid = {},
}</syntaxhighlight>
The [https://springrts.com/wiki/Gamedev:UnitDefs SpringRTS wiki page on unitdefs] says that a unit's cost is 'metalCost' and its speed is just 'speed'. [https://github.com/ZeroK-RTS/Zero-K/blob/master/units/cloakraid.lua The Glaive file] shows us the current value of these parameters, as well as their position in the structure of a unitdef. We can change these values like so:
<syntaxhighlight lang="lua">{
cloakraid = {
metalCost = 50,
speed = 240,
},
}</syntaxhighlight>
Copy this text into a [https://www.base64encode.org/ base64 encoder] and click encode. Here is the resulting encoding.
<code style="display:block;overflow:auto">ewogICAgY2xvYWtyYWlkID0gewogICAgICAgIG1ldGFsQ29zdCA9IDUwLAogICAgICAgIHNwZWVkID0gMjQwLAogICAgfSwKfQ==</code>
Set the Tweak Units modoption to your encoding and start the game. Your infolog should indicate that the modoption loaded successfully.
<samp><pre>[f=-000001] Loading UnitDefs_posts
[f=-000001] Loading tweakunits modoption <------
[f=-000001] Loading tweakunits for cloakraid <------
[f=-000001] Loading FeatureDefs_posts
[f=-000001] Loading WeaponDefs_posts
[f=-000001] Loading ArmorDefs_posts</pre></samp>

== Advanced Example ==
In this example we will change Bandit's damage and range, and add it to the Glaive changes.

As in the simple example, we find the [https://github.com/ZeroK-RTS/Zero-K/blob/master/units/shieldraid.lua Bandit's file] and see that it's called shieldraid. To change Bandit and Glaive at the same time, we add a new sub-table to the table from the previous example.
<syntaxhighlight lang="lua">{
cloakraid = {
metalCost = 50,
speed = 240,
},
shieldraid = {},
}</syntaxhighlight>
Weapon parameters can be found in the [https://springrts.com/wiki/Gamedev:WeaponDefs SpringRTS page on weapon defs], and Zero-K stores them as a sub-table within unitdefs. The range parameter is inside 'LASER' (the internal name of the Bandit's weapon), which is inside the weaponDefs table of Bandit. Weapon damage is further nested inside the damage sub-table of the weapondef.
<syntaxhighlight lang="lua">{
cloakraid = {
metalCost = 50,
speed = 240,
},
shieldraid = {
weaponDefs = {
LASER = {
range = 600,
damage = {
default = 50,
},
},
},
},
}</syntaxhighlight>
As before, we now take this text, [https://www.base64encode.org/ base64 encode] it, and copy it into Tweak Units. Encodings can be shortened by removing whitespace prior to encoding.
<code style="display:block;overflow:auto">e2Nsb2FrcmFpZD17bWF4RGFtYWdlPTUwMCxtYXhWZWxvY2l0eT04LH0sc2hpZWxkcmFpZD17d2VhcG9uRGVmcz17TEFTRVI9e3JhbmdlPTYwMCxkYW1hZ2U9e2RlZmF1bHQ9NTAsfSx9LH0sfSw=</code>

== Mass post-processing ==

The above examples deal with specific values for a single unit (e.g. "make Glaive have 240 speed").
It is also possible to write Lua code that works on units, including changing values for all units or doing some sort of logic. This time, the option is not "Tweak Units" but "Tweak Defs". Again, it should be encoded to base64.

Here's an example:
<syntaxhighlight lang="lua">for name, ud in pairs(UnitDefs) do
if ud.speed then
ud.speed = ud.speed*10
else
ud.health = ud.health*5
end

if ud.metalcost then
ud.metalcost = ud.metalcost*2
end
end</syntaxhighlight>

UnitDefs is a Lua table indexed with unit names as above (for example "cloakraid" for Glaive) whose values are the unit def tables in a similar format as for tweakunits, BUT WITH ALL KEYS LOWERCASE (notice how it's metalcost and not metalCost!). This snippet increases unit speeds 10 times for all mobiles and health 5 times for all statics, and makes all units twice as expensive. Some fields may be <code>nil</code> (for another example, death explosions are weapons but don't have a reload time). Specific Tweak Units values override the values that result from Tweak Defs.

Happy hacking!

[[File:Zk_1_7_11_0_cover.jpg|frame|center]]

[[Category:Development]]{{Navbox manual}}

FAQ

2023-11-06T23:53:27Z

Sprung: Off -> on

'''Frequently Asked Questions'''—Zero-K

==I'm new to Zero-K. Where should I start?==
First, you should read the [[Newbie Guide]] and try some practice games against the <abbr title="artificial intelligence">AI</abbr>. You should definitely try the tutorial, play some or all of the campaign, and/or the more detailed tutorial set available in the ''Help'' menu in the game's lobby.

You can also spectate some online games to see which things are significant.

==How can I unlock Commander modules?==
Visit the [//www.zero-k.info Zero-K Homepage] and log in with your account. You can easily reach this page from the lobby through the "Welcome" tab. From here, you scroll down until you see "You can unlock technology" and click on this link. The link may not be there for you. That's because you do not have to unlock anything from this page; all modules are currently unlocked for all players.

You can see [//zero-k.info/My/UnlockList the list of unlocked technologies] if you're logged in. Unlocking technology during single-player campaign does not affect anything on this page.

==How do I gain rating? ==
You can gain rating if you're winning multiplayer games. You will gain or lose more or less rating based on the skill of your opponent(s).

{{:Rating and Rank}}

==How much XP do I need to reach the next level?==
Mouse over the ''<abbr title="experience points">XP</abbr>'' bar on the home page; the XP needed is displayed in the tooltip.

==How do I un-clump my units to make a decent firing line?==
Read up on [[Unit Management#Micromanagement|micromanaging units]] with ''[[Help for other RTS players#Units and UI|line move]],'' an easy way to make your units form a line whenever you need them to.

==How do I remove a structure that I built?==
Among the best options are:
#[[Reclaim]] it. You get back some resources at the expense of time.
#[[Self Destruct Command|Destroy]] it. Quick, but the explosion may damage nearby units and buildings.
This works with mobile units, too.

==My FPS is low after some time have passed in game. What can I do?==
{{See|Performance Optimizations}}
Try to reduce your graphics settings. To do so, go to the ''Settings'' tab in Zero-K lobby and click ''Graphics Settings''. Some work-intensive elements that you could tone down or disable are shadows, anti-aliasing, and water type. There is also the ''Lowest'' preset you can try for maximum performance. Trying higher presets can help you find the performance and graphic level that works best on your system.

If you're playing on Steam, disable the Steam Overlay, as it negatively affects performance:
* Right-click on Zero-K in your Steam library.
* Select ''Properties'' from the drop-down menu.
* Untick "Enable the Steam Overlay while in-game" in ''General''.

==I'm on Linux and my game hangs/crashes the second time I launch it==
This may be an issue with certain versions of Mono. You might be able to work around it by deleting one or both files in <code>Zero-K/games</code> directory and letting the game rebuild them.

If the game is launched through Steam, you can also try setting the ''Steam Linux Runtime'' as compatibility tool for Zero-K.

==I get ugly bubbles in the minimap/the whole screen flashbangs.==
Do you get bubbles like this?

[[File:FAQ_bg.jpg]]

This is a bug somewhere in Lua drawing with ATI/AMD and OpenGL.

Disable widgets that draw via {{key press|F11}} menu to find the problematic widget.

This should largely be fixed. If it still happens, [[Reporting Bugs|send a bug report]], please.

==I have some game ideas. Where can I post them?==
Visit the [//zero-k.info/Forum Zero-K forum] and pose your ideas in the appropriate section. You can also create a new issue on [//github.com/ZeroK-RTS/Zero-K/issues our development site].

==What do all the in-game abbreviations mean?==
You can look up some abbreviations and acronyms used in the game in [[Abbreviations|our list of abbreviations]]. Some abbreviations unrelated to the game can be looked up on [//en.wiktionary.org/wiki/Appendix:Internet_slang wiktionary]. Another way is to ask other players.

==How can I support the game? Donations?==
On the one hand, you can [//zero-k.info/Contributions donate some coins] so we can pay the server costs. You can also support Zero-K through one of the [//store.steampowered.com/dlc/334920/ donation packs] available on Steam. On the other hand, you can support us by simply playing the game and spreading the word. Feel free to use our [//presskit.zero-k.info/ advertisement material] on your site. Thanks a lot! :-)

==How can I change my Username?==
Follow the guide on [[Name Change|name change]].

==How do I change my password? ==
On your [[User Page|home/account page]], click ''Account maintenance'' and enter your new password.

==I forgot my password/username. Help me pls!==
If you forgot your password or username, please contact the server administrators. They will reset it to something and communicate it to you.

==My mouse cursor in game has disappeared==
This can be caused by driver updates. If it happens, this can be fixed by adding a line to a file in your Zero-K folder that will tell the game to draw the mouse cursor with an alternate method. Under the ''LuaMenu/Config folder'', look for the ''IGL_data.lua'' file and open in a text editor. Look for the section called ''game_settings''.

Adding the line <syntaxhighlight inline>HardwareCursor = 1,</syntaxhighlight> (including the comma) in the middle of this section and saving the file should have your cursor appear the next time you load Zero-K.

Hardware cursor can also be toggled in the [[Ingame Menu#Mouse Cursor|settings menu]] during a game.

==My game crashes/has graphical glitches. How do I fix it?==
First, check the [//springrts.com/wiki/FAQ:trouble troubleshooting FAQ] on the Spring engine wiki and see if your issue is covered there. If you can't find a solution to the problem, you can file a bug report on our forum or [//github.com/ZeroK-RTS Github development site].

==I have a bug report!==
You can post in the [//zero-k.info/Forum?categoryID=3 ''Help and Bugs'' sub-forum] or make an issue report on [//github.com/ZeroK-RTS ZeroK-RTS Github] (more technical). There is also a #support channel on [https://discord.gg/aab63Vt Discord] you can post to.

Please include diagnostic logs as appropriate. You can automatically upload the log from the game's lobby by pressing the <samp>Help</samp> button, then <samp>Report A Bug</samp>. During this step, a webpage should open with your diagnostic log. Be sure to make note of the address before closing it.

Otherwise, look for ''infolog.txt'' and ''infolog_full.txt'' in your installation folder. Use [//www.pastebin.com pastebin] to show the contents of your ''infolog'' files and give the resulting link instead of posting the whole thing on the forum or github.

==Steam won't log me in anymore!==

The Steam service and its login servers experience occasional maintenance downtime (usually on Tuesday) that can cause your Zero-K account to fail to connect. First you should [https://steamstat.us check if steam is down in your region]. If Steam services in your region are showing as OK, try the next step.

In the lobby client, go to "Settings > Lobby > Login with Steam" and make sure this and "Login automatically" are checked on. If you want to set a password and unlink your account from steam, see [[Account Management]].

==My question isn't answered here. Where can I ask my question?==
As above, you can visit the [//zero-k.info/Forum forum] and ask your question in one of the listed sections.

You can also ask other players to get help.

{{Navbox manual}}

Promotion

2023-10-17T15:26:29Z

Sprung:

=== There is no memetics division ===

ZK doesn't really have any sort of coordinated promotion effort ongoing. The dev team are technical people and won't be of much help beyond general high-level guidance. If you want to do stuff and contribute promotion effort, feel free to, but you'll most likely be on your own and have to both figure out what to do, and actually do that grunt work, yourself. Of course you can grab other people to help you, but again, everything is grassroots so finding those people and setting up some sort of coordination is still up to you. You, the reader, are the head of the memetics division.

=== Known ongoing work ===

Here is a summary of the promotion efforts that are ongoing, and the people who have offered their skills.

Existing promotion people
* 64-Bit Dragon - Runs the ZK twitter and casts games on Youtube https://www.youtube.com/@64-Bit_Dragon https://twitter.com/ZeroKTeam
* nr1_riposteR_fan - has access to ZK twitter

Potential helpers
* AltoArts - Experience making promotional videos.

Promotion

2023-10-17T15:19:20Z

Sprung:

=== There is no memetics division ===

ZK doesn't really have any sort of coordinated promotion effort ongoing. The dev team are technical people and won't be of much help beyond general high-level guidance. If you want to do stuff and contribute promotion effort, feel free to, but you'll most likely be on your own and have to both figure out what to do, and actually do that grunt work, yourself. Of course you can grab other people to help you, but again, everything is grassroots so finding those people and setting up some sort of coordination is still up to you.

=== Known ongoing work ===

Here is a summary of the promotion efforts that are ongoing, and the people who have offered their skills.

Existing promotion people
* 64-Bit Dragon - Runs the ZK twitter and casts games on Youtube https://www.youtube.com/@64-Bit_Dragon https://twitter.com/ZeroKTeam
* nr1_riposteR_fan - has access to ZK twitter

Potential helpers
* AltoArts - Experience making promotional videos.

Promotion

2023-10-17T15:17:50Z

Sprung:

=== There is no memetics division ===

ZK doesn't really have any sort of coordinated promotion effort ongoing. The dev team are technical people and won't be of much help beyond general high-level guidance. If you want to do stuff and contribute promotion effort, feel free to, but you'll most likely be on your own and have to do the grunt work yourself. Of course you can grab other people to help you, but again, everything is grassroots so finding those people and setting up some sort of coordination is still up to you.

=== Known ongoing work ===

Here is a summary of the promotion efforts that are ongoing, and the people who have offered their skills.

Existing promotion people
* 64-Bit Dragon - Runs the ZK twitter and casts games on Youtube https://www.youtube.com/@64-Bit_Dragon https://twitter.com/ZeroKTeam
* nr1_riposteR_fan - has access to ZK twitter

Potential helpers
* AltoArts - Experience making promotional videos.

Promotion

2023-10-17T15:13:13Z

Sprung:

=== There is no memetics division ===

ZK doesn't really have any sort of coordinated promotion effort ongoing. The dev team are technical people and won't be of much help beyond general high-level guidance. If you want to do stuff and contribute promotion effort, feel free to, but you'll most likely be on your own and have to do the grunt work yourself. Of course you can grab other people to help you, but again, everything is grassroots so finding those people and setting up some sort of coordination is still up to you.

=== Known ongoing work ===

Here is a summary of the promotion efforts that are ongoing, and the people who have offered their skills.

Existing promotion people
* 64-Bit Dragon - Runs the ZK twitter and casts games on Youtube https://www.youtube.com/@64-Bit_Dragon https://twitter.com/ZeroKTeam

Potential helpers
* AltoArts - Experience making promotional videos.

Startbox API

2022-07-31T02:00:52Z

Sprung: Formatting.

== Start boxes ==

Each team has a defined starting area in which its players can spawn their commanders - these are called start boxes. Map makers can define how these areas look like by including a config file inside their map archive.

== The config file ==

The file which you need to include is
mapconfig/map_startboxes.lua

It consists of Lua code which returns 2 tables: one with the start box layout for the current match and one that contains possible box counts.

For examples see the bottom of this page.

== Box counts ==

Let's start from the last table because it is the simplest. This is just a list of how many teams the map is designed for.

Let's take [http://zero-k.info/Maps/Detail/8162 Throne] as an example. It has an outer ring with 7 starting areas so it can be played as a 7-team FFA. There are also rings with 3 and 5 areas so 3- and 5-team FFAs are also possible setups. Finally, you could play a duel between any two positions from the same ring. (The real Throne config is a fair bit more complicated than that but you get the idea.)

Thus, the possible team counts are 2, 3, 5, and 7. Let's define a Lua table for that:
local playercounts = {2, 3, 5, 7}

This is mostly important for fancy FFA maps. Simple duel/teamgame maps will usually just have 2 as the only value here:
local playercounts = {2}

== The boxes ==

Now, the most tedious part. The boxes do not need to actually be boxes, they can be any arbitrary shape (even concave or disjoint). This is achieved by having the boxes defined as a set of polygons.

There is a widget which lets you draw the polygons ingame, it's called "Startbox Editor" and is under the "For Developers" tab in the widget list (press Alt+F11, and don't touch anything else unless you know what you're doing).

To draw a polygon, use LMB - either drag a line or click points:

[[File:Startbox API 1.jpg]]

Once you draw a full loop, press RMB to close it. Make sure the line does not cross itself. Finished polygons are a bit darker.

[[File:Startbox API 2.jpg]]

Now you can add another polygon if you want. These will all be a part of the same team.

[[File:Startbox API 3.jpg]]

If you want to delete the last created polygon, press D.
Once you are satisfied with the area, press S. Now you can draw the area for another team.

Once you create all the boxes, go to your Spring directory and find the infolog. There you will see a bunch of code like
boxes = {
stuff
},

Each of those tables is a team's startbox. The config is an array of each team's startbox data. The box data from the generator will go to a team's config entry. Like this:
local main_config = {
{
boxes = {
stuff
},
-- more entries will go there later!
},

-- another team's box data
{
boxes = {
stuff
},
},
}

The layout is a normal Lua table so you can use all the usual table manipulation methods. For example you could add more area based on how many people there are, or generate them dynamically.

=== The recommended start points ===

This sub-table defines recommended start points within each box. These are points on which CAI bots will spawn. The first point is special: human players who did not pick start position will also spawn here and so will any extra CAI if there are more of them than the spots; as such having at least one startpoint in each box is mandatory. These points are also marked on people's UI as circles.

Defining these is very simple. It's very similar to how start areas were defined. Ingame you can hold Space over a point to see its coordinates. These are written down for boxes similarly to the areas:
local main_config = {
{
boxes = {
stuff
},
startpoints = {
{123, 456}, -- X, Z
{654, 321},
-- as many as you want, it's good if there are as many as you want people per team
},
},
{
boxes = {
stuff
},
startpoints = {
{789, 789},
{987, 987},
},
},
}

Of course, the start positions should match the areas, though they don't have to.

== Putting these together ==

You can give each team a name, alongside a shorter backup if the first one is too large. Here's how:

{
boxes = { stuff },
startpoints = { stuff },
nameLong = "South-West",
nameShort = "SW",
}

It serves to identify the team so while it's good to use something that describes placement, you can get creative. For example:
* "North", "South-East"
* "5 o'clock"
* real-world style maps could have names like "Russia" or "America"
* asymmetric maps can use landmarks, for example "Lake" vs "Desert"
* for missions it's good to use storyline names, eg "Empire" vs "Dynasty"

== Summary ==

Now just return the config table and the playercounts table.
return main_config, playercounts

The exact format for the config table that should get returned is

{
{ -- a single team's data
boxes = {
{ -- a polygon
{123, 456}, -- a vertex of the polygon. X, Z.
{234, 567}, -- another vertex
{345, 678},
-- more vertices
},
{ -- another polygon
-- vertices
},
-- more polygons
},
startpoints = {
{123, 456}, -- X, Z
{654, 321},
-- more points
},
nameLong = "longer string with team name",
nameShort = "short",
},
{ -- another team's data
boxes = { ... },
startpoints = { ... },
nameLong = "...",
nameShort = "...",
},
-- more teams
}

== Advanced stuff ==
The config has access to Spring Lua API so it is possible to do a lot of dynamic things. In particular, you can use math.random without worry.

You can make stuff dependent on the game mode. There are functions which return the gametype, such as `Spring.Utilities.Gametype.is1v1()`. The full list is here: https://github.com/ZeroK-RTS/Zero-K/blob/master/LuaRules/Utilities/teamFunctions.lua#L74

An important thing is that #Spring.GetAllTeams() will return a wrong value due to fake technical teams and Gaia. Instead, use Spring.Utilities.GetTeamCount() to get the real number of teams.

== Examples ==

* [https://github.com/ZeroK-RTS/Zero-K/blob/master/LuaRules/Configs/StartBoxes/SpeedMetal.lua SpeedMetal] - the simplest layout, just two squares.
* [https://github.com/ZeroK-RTS/Zero-K/blob/master/LuaRules/Configs/StartBoxes/DeltaSiegeDry.lua DSD] - huge polygons, but otherwise very simple.
* [https://github.com/ZeroK-RTS/Zero-K/blob/master/LuaRules/Configs/StartBoxes/Sever%201.lua#L343 Sever] - shows an example of smaller boxes for 1v1 and larger for teams.
* [https://github.com/ZeroK-RTS/Zero-K/blob/master/LuaRules/Configs/StartBoxes/Isle%20of%20Grief%200.2.lua Isle of Grief] - shows a smart approach, one of the boxes is not defined rigidly but is a mirror of the other (only really feasible for rough boxes or perfectly symmetrical maps).
* [https://github.com/ZeroK-RTS/Zero-K/blob/master/LuaRules/Configs/StartBoxes/Aum_1.1.lua Aum] - another small trick, this time 5-way radial symmetry.
* [https://github.com/ZeroK-RTS/Zero-K/blob/master/LuaRules/Configs/StartBoxes/Throne%20v1.lua Throne] - multiple boxes defined, with a system to pick some of them based on how many teams there are.
* [https://github.com/ZeroK-RTS/Zero-K/blob/master/LuaRules/Configs/StartBoxes/Speed_Ball_10x10.lua Speedball] - shows boxes that are generated completely algorithmically.
* [https://github.com/ZeroK-RTS/Zero-K/blob/master/LuaRules/Configs/StartBoxes/Mearth_v4.lua#L6 Middle-Earth] - interesting team names.
* [https://github.com/ZeroK-RTS/Zero-K/blob/master/LuaRules/Configs/StartBoxes/Adansonia%20v2.lua Adansonia v2] - shows synchronizing boxes across map versions.
* [https://github.com/ZeroK-RTS/Zero-K/blob/master/LuaRules/Configs/StartBoxes/duck.lua Duck] - boxless config for silly maps where everybody can start anywhere.

[[Category:Development]]{{Navbox manual}}

Startbox API

2022-07-31T02:00:10Z

Sprung: Indexing is now from 1

ZK Map Making Guide

2022-04-29T15:53:19Z

Sprung: Fix a typo

Also see:

* [[Map Creation]]
* [https://docs.google.com/document/d/1PL8U2bf-c5HuSVAihdldDTBA5fWKoeHKNb130YDdd-w/edit# Advanced guide using WorldMachine], by Beherith

DISCLAIMER: This guide is a work in progress (particularly with respect to using particular pieces of software) but the basic framework here should give you a good start.

= Minimal Brief Guide =

For more detail on each of these steps read the later sections of the document.

This guide assumes that you are using a version of Zero-K installed through Steam. You can still make maps if you installed by some other method but you may need to modify some of the later steps.

If you want to see what the map's file structure is meant to look like overall, scroll to the [[https://zero-k.info/mediawiki/index.php?title=ZK_Map_Making_Guide#Skeleton_Of_A_Map Skeleton Of A Map]] section. It's also a good idea to un7zip some existing maps and take a look to see how they are set up (and borrow anything which seems useful for your map).

== Download Tools ==

* 7zip - https://www.7-zip.org/download.html
* pymapconv - clone or download https://github.com/Beherith/springrts_smf_compiler somewhere, then copy pymapconv.exe and nvdxt.exe to a new directory to keep things simple
* map blueprint - clone or download https://github.com/Aquanim/ZKMapBlueprint

[[File:Mapguide_download_aquanim_blueprint.png|Map blueprint download]]

== Create Images ==

For a 10x10 (TitanDuel-size) map, create the following images with a tool of your choice:

* A height map grayscale image with dimensions 641 x 641, saved as an 8-bit .bmp or a 16-bit .png. (The latter is preferred but not all tools offer 16-bit output.) The brighter a pixel is the higher the corresponding part of the map will be.
* A texture map colour image with dimensions 5120 x 5120, saved as a .bmp

For a different size map, multiply the height/width of the map by 64 and add 1 to get the right size for the heightmap; multiply the height/width of the map by 512 to get the right size for the texture map.

Different image formats ''might'' work but are just as likely to cause difficult-to-diagnose errors.

Put these images in the same directory as pymapconv.exe from the previous step (may not strictly be required but keeps things simple). 

Useful tools: Spring Map Edit (SME), Springboard, TerreSculptor, World Machine, GIMP, Blender, any image editing software really

== Compile Your Map ==
Run pymapconv.exe and fill in the following fields...
* An output file name - ideally this should be the name of your map, possibly with a version number. File extension .smf, will also generate a .smt. '''IMPORTANT:''' Do not rename these files after compiling!
* Use the buttons to select the texture and heightmap images you made in the previous step.
* I expect the minimum/maximum height values to be overridden by mapinfo.lua later but you might as well set them.
* Scroll down to the NVDXT option and make sure it says "-Sinc -quality_highest". Also probably a good idea to tick the CLEAN option.
* Untick everything else, press "Save options as" if you like, then press the "Compile" button. 

Troubleshooting:
* If your map's minimap looks like it is from an old version of your map or a different map entirely, there is probably an old minimap file which the compiler is reading. In the directory where your compiler .exe is, delete any images which look like a minimap (probably something like mini.bmp and/or mini.dds) then recompile.
* If your map texture looks all pinkish ingame you probably renamed the .smf and .smt files. Regenerate them and be extra sure not to rename them this time. If the issue persists there might be other reasons this can happen, consult the #zkmap channel.

== Construct .sdd File ==
* Rename ZKMapBlueprint_v0.0.sdd to have the name of your map. A version identifier is advisable as well. Keep the .sdd extension.
* Copy the .smf and .smt files produced by pymapconv.exe into the /maps subfolder of the .sdd folder. (There should be mapblueprint.smf and mapblueprint.smt files here, you can delete them.)
* In the root of the .sdd folder there should be a file "mapinfo.lua". Open this with a text editor. This file contains a bunch of stuff but there are only a few items we are interested in for now:
** Near the start of the file change the ''author'', ''description'', ''name'', ''shortname'' and ''version'' variables to suit you and your map.
** Scroll down a bit to the "smf" section and change the ''maxheight'' and ''minheight'' numbers to suit your map. Also change the file name after ''smtFileName0'' so that it has your .smt file's name.
* To test your map, copy the .sdd directory into the /maps folder of your Zero-K install. In the settings make sure that "Only featured maps" is disabled. Then open a Skirmish game, click on the current map, select your map from the list, and play. (You might want to make the enemy AI inactive. The minimap in the lobby will be blank, don't worry about this for now.)
* If you want to change your map you will need to replace the files in your ZK maps folder, then restart ZK, in order to load the new version.

== Metal and Startboxes ==
Now that you can look at your height and texturemap ingame this is a good time to sort out your metal spots and start locations.
=== Metal spots ===
In the /mapconfig subfolder of the .sdd file there is a "map_metal_layout.lua" file. The blueprint contains two metal spots as an example; replace them with your own.

=== Startboxes ===
In the /mapconfig subfolder of the .sdd file there is a "map_startboxes.lua" file. This specifies each team's startboxes as well as default start locations.

Some hints for configuring the metal and startbox files:

* Startboxes are specified by their corner points reading clockwise around the polygon. More than one separate box for a given team is possible.
* Holding SPACE ingame will display a dialog box which (among other things) gives the X and Z coordinates of wherever your cursor is.
* The metal and startbox files are just LUA scripts. This means you don't have to write simple numbers to specify locations; you can perform arithmetic to make sure your map setup is symmetric (the startbox of the South-East team in the blueprint is an example). More advanced scripting is also possible, for example to make your startbox configuration dependent on the number of players or allyteams. See the [[http://zero-k.info/mediawiki/index.php?title=Startbox_API#Advanced_stuff Startbox API page]] .

=== Useful Tools ===

[[https://zero-k.info/mediawiki/index.php?title=ZK_Map_Making_Guide#Startbox_Editor_Widget Startbox Editor Widget]]
[[https://zero-k.info/mediawiki/index.php?title=ZK_Map_Making_Guide#Metal_Spot_Placer Metal Spot Placer]]

== Optional Extras ==
Scroll down to section 3 to see how to add...
* Features (geovents, trees, rocks, etc)
* DNTS (fancy map details and specular map)
* Fancy mapinfo stuff (lighting, water effects, etc)
* Skybox
* Other nonsense (particle effects, sound, etc)
* Lava

== Upload ==

Compress the contents of the .sdd file into a 7z, then change the file extension to “.sd7”.

If you remove the .sdd from your game maps directory and put the .sd7 in its place, the map should still work. It is a good idea to test the .sd7 before uploading since there are several *very* easy mistakes to make in the compression process.

'''IMPORTANT:''' Make sure that when you open the archive you see mapinfo.lua and not your .sdd folder! If you get this wrong the map will not work correctly. If you get an error saying that a .smd file is missing this is probably the problem.

'''IMPORTANT:''' When you compress to 7z make sure the compression is “non-solid”. If using 7zip this is done by setting the "Solid Block size" option to "non solid".

=== Uploading to Zero-K Server ===

* Go to https://zero-k.info/Maps
* Scroll down until you find the "Upload map or game (sd7 or sdz):" file on the right-hand side
* Upload your map
* Test your map on the live server so there is a publically accessible replay or two - games against AIs are fine
* Ask a moderator to support/feature your map (they will also tag it as 1v1/teams/hilly/flat/whatever as appropriate)

If the upload step doesn't work there are two potential reasons:
* Your map isn't set up right. Test it locally again and make sure your map works.
* Something on the server has gone wrong. AFTER testing your map locally and finding that it works there, contact an admin. Uploading your map to a file-sharing service so the admin can look at it may help.

=== Uploading to Springfiles for use in other Spring communities ===

The old Springfiles website is defunct and has been replaced by https://springfiles.springrts.com/?type=0

Somebody who knows how the upload process works now should fill this in. Should hopefully be simpler than old Springfiles though.

= Skeleton Of A Map =

All you *really* need is the stuff in solid grey boxes: mapinfo.lua, .smf and .smt files, a metal layout, and a startbox config.

[[File:Mapskeleton.png|The skeleton of a map]]

(Note: Some of the things labelled as "necessary" probably technically aren't; there are many ways to construct a map that Spring will accept. This guide will walk you through one that should be reasonably coherent and up to date.)

= Tools and Resources =

== Springboard ==

[https://springboard-core.readthedocs.io/en/latest/installing.html Springboard Documentation]

[[Springboard Tutorial]] on this wiki (under construction)

=== Installation ===
[https://github.com/Spring-SpringBoard/SpringBoard-Core/ Github page]
Scroll down to the "Installing" section and get the appropriate installer.

== SpringMapEdit ==

=== Installation ===
[https://springfiles.com/spring/development/spring-map-edit Springfiles page]

== Nobiax Texture Pack ==

== Startbox Editor Widget ==
Load your map in ZK, press Alt-F11 to access the widget list, press "Search" and enter "Startbox". Enable the Startbox Editor widget. The ingame description doesn't say much so let's consult the [https://github.com/ZeroK-RTS/Zero-K/blob/90d61099e3fb8509645cf16d3fa2982150c81bdd/LuaUI/Widgets/dbg_startbox_editor.lua widget source file]:

[[Image:Startboxeditor1.png]]

...well, that's not a good sign. Scroll down a bit further:

[[Image:Startboxeditor2.png]]

That's more like it. Follow those instructions to create your startboxes, then open your infolog.lua (in the main zero-k directory) after you exit to retrieve the startbox information for copying into map_startboxes.lua. It's probably a good idea to turn the widget off after you are done with it.

== Metal Spot Placer ==
Load your map in ZK, press Alt-F11 to access the widget list, press "Search" and enter "Metal Spot". Enable the Metal Spot Placer widget. As per the ingame description:
* Press Alt-M to enable the widget
* Click in locations on the map to place metal points
* Press Alt-M again to disable the widget and print a list of metal points to the infolog

Then open your infolog.txt (in the main zero-k directory) after you exit to retrieve the startbox information for copying into map_metal_layout.lua. Check that the metal point values for each mex point are as you want them to be. It's probably a good idea to turn the widget off after you are done with it.

== Upspring ==

A tool for modifying models like those of tree features, etc. Might be useful if a feature is too large, too small, or not centered properly. I'll leave this guide to somebody who actually understands modelling.

= Other Stuff =

== Features (geovents, trees, rocks, etc) ==

This method of placing features requires you to have some s11n gadgets in /LuaRules/Gadgets and some s11n and lcs stuff in the /libs/ folder. If your map doesn't have these then get them from the blueprint or some other map.

* Put the files defining the features you want in your map file. This includes a definition in the /features subdirectory, model files in the /objects3d directory, and textures in the /unittextures directory. The easiest way to get these is to borrow them from existing maps. There is a features library as well... ask around in #zkmap for a link then update this page.
* Load your map in Springboard
* Delete any features you have marking mex locations, otherwise you will end up with two copies of them and that is bad.
* Place features using Springboard.
* Open the "Export" window in Springboard, choose a file name, set the file type to "s11n object format" and export the file.
* The file will (probably?) have been exported to <springboard exe directory>/data/springboard/exports - copy this s11n file to the ./mapconfig subdirectory of your map.
* Make sure that in ./libs/s11n/s11n_load_map_features.lua that the "modelPath" variable points at your s11n file.

Troubleshooting:
* IF your features do not move when the ground under them is terraformed (a particular problem for geovents) go to ./libs/s11n/features_s11n.lua, look for the "CreateObject" function, and change it so that SetFeatureMoveCtrl is not being used to set MoveCtrl to true.

== DNTS ==

If you don't use DNTS but you do set detailTex in the "resources" section of mapinfo.lua then you will get some general detail map. This works better than flat colour but we can get fancier.

* Put the .dds or .tga files defining the detail map (commonly grass, pebbles, rocks, etc.) you want in your /maps subdirectory. Again these are most easily found by borrowing from other maps. [http://beherith.eat-peet.net/stuff/nobiax_spring_dnts/nobiax_spring_dnts.html This page] has some that may work (possibly with some effort).
* In mapinfo.lua, in the "resources" section, set splatDetailNormalTex1, splatDetailNormalTex2, splatDetailNormalTex3, splatDetailNormalTex4 to point to your detail files. These will in order be defined by the red, green, blue and alpha channels of your distribution image.
* Set splatDistrTex to point to your distribution image. This defines where each detail type appears on your map. This image will be stretched over your map; powers of two in the resolution are advised.
* Set specularTex to point to your specular image; what colour of light will be reflected from each part of the map. It is easy to go overboard with this so taking your texture map, darkening it significantly (or possibly increasing its transparency), and tuning from there is an okay strategy. Again, this image will be stretched over your map; powers of two in the resolution are advised.
* There is also some lightemission thing that I have not used and don't really understand [https://springrts.com/wiki/Mapdev:lightemission here]. The example image looks like Otago so try asking TheMooseIsLoose for advice?

== Water and lighting settings ==

I'm not an expert, tune these for yourself until it looks good. Try reading [https://springrts.com/wiki/Mapdev:water these] [https://springrts.com/wiki/Mapdev:mapinfo.lua#Lighting pages].

== Skybox ==

Borrow one from some other map then set it in mapinfo.lua, atmosphere section, variable "skyBox". If you want to make one yourself apparently pymapconv can put it in the right format.

== Particle and sound effects ==

Find a map that does the thing you want to do, look at how that map did it. For reference some fairly simple examples can be found in Rogues River (sound effects), Aurelian (precipitation), and Mercurial (plumes from the water).

== Lava ==

Good luck... I'm not sure anybody has come up with an entirely bug-free implementation of this yet. Banana Republic might be your best bet for a reference.

== Lobby/Website minimap image ==

This minimap image is generated from your map's texture, but unlike the ingame minimap does not have water drawn on it. If you would like your map's lobby/website image to be different, you need to create replacement images and provide them to somebody with the appropriate server access to overwrite the existing minimaps (not just any admin can do this). Anarchid has handled most of these in recent years. Ideally you only want to do this once, so wait until your map is up to a final release version before making the replacement image.

Required images for a map called "map name v1.0":
* A minimap image with the name map_name_v1.0.minimap.jpg with maximum height/width 1024.
* A thumbnail image with the name map_name_v1.0.thumbnail.jpg with maximum height/width 96.
'''IMPORTANT:''' Replace any spaces in your map name with underscores.

Find the default images for your map on the server to figure out reasonable dimensions. Screenshotting your ingame minimap and then rescaling it is a reasonable way to get a minimap image with water on it.

{{Navbox manual}} [[Category: Development]]

Award

2022-03-15T15:40:27Z

Sprung: Slow/EMP don't count for the averages.

At the end of every battle, players are '''award'''ed with shiny trophies for various achievements during the game. Some awards are presented every game, while others are less common. It takes outstanding performance with the relevant unit set to receive an award.

There are also event-based awards which are never awarded in normal games, for example tournament cups.

All damage-related awards except Big Purple Heart use metal value to compare performance. Such awards are only given if the damage dealt with those weapons/units compares favorably to the average damage done by other players.

== The Awards ==

=== Generic Awards ===
* http://zero-k.info/img/Awards/trophy_pwn.png '''Complete Annihilation''': always awarded to the player who dealt the most damage.
* http://zero-k.info/img/Awards/trophy_ouch.png '''Big Purple Heart''': always awarded to the player who received the most health damage.
* http://zero-k.info/img/Awards/trophy_reclaim.png '''Spoils of War''': efficient usage of reclaim.
* http://zero-k.info/img/Awards/trophy_mex.png '''Mineral Prospector''': building metal extractors.
* http://zero-k.info/img/Awards/trophy_mexkill.png '''Loot & Pillage''': raiding enemy metal extractors.
* http://zero-k.info/img/Awards/trophy_shell.png '''Turtle Shell''': effective use of defense.
* http://zero-k.info/img/Awards/trophy_nux.png '''Apocalyptic Achievement Award''': employing superweapons.
* http://zero-k.info/img/Awards/trophy_air.png '''Air Force General''': exceptional play with airborne units.
* http://zero-k.info/img/Awards/trophy_navy.png '''Fleet Admiral''': successful ship usage.
* http://zero-k.info/img/Awards/trophy_slow.png '''Traffic Cop''': applying slow damage.
* http://zero-k.info/img/Awards/trophy_emp.png '''EMP Wizard''': dealing EMP damage.
* http://zero-k.info/img/Awards/trophy_kam.png '''Kamikaze Award''': heroic usage of self-destructing units.
* http://zero-k.info/img/Awards/trophy_terra.png '''Legendary Landscaper''': excessive terraforming.
* http://zero-k.info/img/Awards/trophy_comm.png '''Master and Commander''': using your commander like a boss
* http://zero-k.info/img/Awards/trophy_fire.png '''Master Grill-Chef''': dealing fire damage.
* http://zero-k.info/img/Awards/trophy_cap.png '''Master of Puppets''': capturing enemy units.
* http://zero-k.info/img/Awards/trophy_rezz.png '''Vile Necromancer''': resurrecting wreckage.
* http://zero-k.info/img/Awards/trophy_head.png '''Head Hunter''': eliminating enemy commanders.
* http://zero-k.info/img/Awards/trophy_share.png '''Share Bear''': sharing units to allies.
* http://zero-k.info/img/Awards/trophy_vet.png '''Decorated Veteran''': extremely efficient usage of a single unit.
* http://zero-k.info/img/Awards/trophy_disarm.png '''Peacemaker''': disarming enemy units.

=== Chicken Awards ===
* http://zero-k.info/img/Awards/trophy_heart.png '''Queen Heart Breaker''': killing the Chicken Queen.
* http://zero-k.info/img/Awards/trophy_sweeper.png '''Land Sweeper''': destroying Chicken Roosts.
* http://zero-k.info/img/Awards/trophy_dragon.png '''Dragon Slayer''': eliminating Chicken Dragons.

=== Event Awards ===
* http://zero-k.info/img/Awards/trophy_gold.png http://zero-k.info/img/Awards/trophy_silver.png http://zero-k.info/img/Awards/trophy_bronze.png '''Tournament Cups''': awarded for the winners of the monthly tournaments.
* http://zero-k.info/img/Awards/coingold.png http://zero-k.info/img/Awards/coinsilver.png http://zero-k.info/img/Awards/coinbronze.png '''Coins''': awarded for minor community events.

== Technical details ==

Some awards have flat requirements for being awarded:
* Mineral Prospector / Loot & Pillage take a minimum of 15 mexes built/killed to earn.
* Legendary Landscaper takes a minimum of 1000m worth of terraform.
* Head Hunter / Dragon Slayer / Land Sweeper require 3/3/20 commander/dragon/nest kills.
* Master of Puppets / Vile Necromancer / Share Bear require 1000/3000/5000m worth of units captured/resurrected/shared respectively.
* Decorated Veteran requires the unit to make 300% cost, with a minimum of 1000m.
* Queen Heartbreaker requires the chicken queen to die.

Big Purple Heart operates on health and considers environmental damage (such as collisions, forest fires, or lava). All other damage awards operate on cost and only consider PvP damage.

Using a damage type is not enough to be eligible for the appropriate award. Each award has a dynamic threshold that scales with the general game size. Eligibility is decided thus:
* Take the average physical damage done by all players except yourself.
* Multiply by a per-award factor given in the table below.
* Compare your own damage with the given type. You are eligible if your damage is higher.

{| class="wikitable"
|+ Difficulty factors
|-
! Award
! Multiplier
|-
| EMP Wizard
| 1.2
|-
| Fleet Admiral Airforce General Traffic Cop
| 1
|-
| Turtle Shell Master Grill-Chef
| 0.5
|-
| Apocalyptic Achievement Award Kamikaze Award Master and Commander
| 0.3
|-
| Spoils of War
| 0.06
|}

=== Example ===

* <var>A</var> did 900m of damage composed of 450m of fire damage, 350m of kamikaze damage and 100m general damage.
* <var>B</var> did 800m kamikaze damage and 50m slow damage.
* <var>C</var> did 1200m general damage and 50m EMP damage.

The average of others' damage:
* For <var>A</var>, it is (800 + 1200) / 2 = 1000. Note that the slow dealt by B and EMP dealt by C are not "physical" so do not count.
* For <var>B</var>, it is (900 + 1200) / 2 = 1050.
* For <var>C</var>, it is (900 + 800) / 2 = 850.

The multiplier for kamikaze is 0.3 and for fire is 0.5, so:
* <var>A</var> would have to do 1000 × 0.5 = 500 fire damage to be eligible. He did 450, so he won't get it.
* <var>A</var> would have to do 1000 × 0.3 = 300 kamikaze damage. He did 350, so he is eligible.
* <var>B</var> would have to do 1050 × 0.3 = 315 kamikaze damage. He did 800, so is also eligible.

<var>B</var> did 800 kamikaze damage and <var>A</var> did 350, so <var>B</var> gets the kamikaze award.
Nobody is eligible for the fire award.
<var>C</var> did the most total damage, so gets the Complete Annihilation award.
{{Navbox manual}}

Quick Stat Tweaks

2022-03-08T12:14:43Z

Sprung: Github dislikes case mismatch

The Tweak Units modoption can be used to modify many unit and weapon parameters. It can be used for rapidly testing balance changes or just for making a quick game mode. It has limitations and should not be used for large mod projects, see [[Mod Creation]] and [[How To Play Mods]] to get started on full modding.

[[File:Tweakunitsdefs.png]]

Stat tweaks can be saved and shared as a [[Custom Modes | Custom Mode]].

== Workflow ==
The Tweak Units modoption overwrites unit parameter (called unitDefs) as they are loaded. The modoption requires a base64-encoded Lua array of differences. Here is how to use it.
* Make a Lua table in an empty file.
* For each unit you wish to modify, add an empty table indexed by the [[Internal unit names|internal name]] of the unit to your table.
* Search for the units you wish to modify in the [https://github.com/ZeroK-RTS/Zero-K/blob/master/units Zero-K repository].
* Copy the parameters you wish to modify into the table, maintaining the structure of the unitDef table.
* [https://www.base64encode.org Base64 encode] your table.
* Put the base 64 encoding of your table into the Tweak Units modoption.
* Start the game.
* Check infolog.txt in your install directory and fix your syntax errors.

Check out the [https://springrts.com/wiki/Gamedev:UnitDefs unit def] and [https://springrts.com/wiki/Gamedev:WeaponDefs weapon def] pages on the SpringRTS wiki for definitions of many of the parameters. Search the Internet for tutorials on Lua tables.

== Limitations ==
Tweak Units cannot be used to change parameters that are part of a unit's animation, and access to some of the more unique abilities may be missing. In particular, the aiming speed of most units cannot be changed with this method.

== Simple Example ==
In this example we make Glaive faster and healthier.

Start with an empty Lua table.
<syntaxhighlight lang="lua">{
}</syntaxhighlight>
A search through the [https://github.com/ZeroK-RTS/Zero-K/blob/master/units unitdef repository] reveals that Glaive is known as cloakraid internally. [https://github.com/ZeroK-RTS/Zero-K/blob/master/units/cloakraid.lua This] is the file. Add an empty table with key 'cloakraid'.
<syntaxhighlight lang="lua">{
cloakraid = {},
}</syntaxhighlight>
The [https://springrts.com/wiki/Gamedev:UnitDefs SpringRTS wiki page on unitdefs] says that a unit's health is 'maxDamage' and its speed is 'maxVelocity'. [https://github.com/ZeroK-RTS/Zero-K/blob/master/units/cloakraid.Lua The Glaive file] shows us the current value of these parameters, as well as their position in the structure of a unitdef. We can change these values like so:
<syntaxhighlight lang="lua">{
cloakraid = {
maxDamage = 500,
maxVelocity = 8,
},
}</syntaxhighlight>
Copy this text into a [https://www.base64encode.org/ base64 encoder] and click encode. Here is the resulting encoding.
<code style="display:block;overflow:auto">ewogICAgY2xvYWtyYWlkID0gewogICAgICAgIG1heERhbWFnZSA9IDUwMCwKICAgICAgICBtYXhWZWxvY2l0eSA9IDgsCiAgICB9LAp9</code>
Set the Tweak Units modoption to your encoding and start the game. Your infolog should indicate that the modoption loaded successfully.
<samp><pre>[f=-000001] Loading UnitDefs_posts
[f=-000001] Loading tweakunits modoption
[f=-000001] Loading tweakunits for cloakraid
[f=-000001] Loading FeatureDefs_posts
[f=-000001] Loading WeaponDefs_posts
[f=-000001] Loading ArmorDefs_posts</pre></samp>

== Advanced Example ==
In this example we will change Bandit's damage and range, and add it to the Glaive changes.

As in the simple example, we find the [https://github.com/ZeroK-RTS/Zero-K/blob/master/units/shieldraid.Lua Bandit's file] and see that it's called shieldraid. To change Bandit and Glaive at the same time, we add a new sub-table to the table from the previous example.
<syntaxhighlight lang="lua">{
cloakraid = {
maxDamage = 500,
maxVelocity = 8,
},
shieldraid = {},
}</syntaxhighlight>
Weapon parameters can be found in the [https://springrts.com/wiki/Gamedev:WeaponDefs SpringRTS page on weapon defs], and Zero-K stores them as a sub-table within unitdefs. The range parameter is inside 'LASER' (the internal name of the Bandit's weapon), which is inside the weaponDefs table of Bandit. Weapon damage is further nested inside the damage sub-table of the weapondef.
<syntaxhighlight lang="lua">{
cloakraid = {
maxDamage = 500,
maxVelocity = 8,
},
shieldraid = {
weaponDefs = {
LASER = {
range = 600,
damage = {
default = 50,
},
},
},
},
}</syntaxhighlight>
As before, we now take this text, [https://www.base64encode.org/ base64 encode] it, and copy it into Tweak Units. Encodings can be shortened by removing whitespace prior to encoding.
<code style="display:block;overflow:auto">e2Nsb2FrcmFpZCA9IHttYXhEYW1hZ2UgPSA1MDAsbWF4VmVsb2NpdHkgPSA4LH0sc2hpZWxkcmFpZCA9IHt3ZWFwb25EZWZzID0ge0xBU0VSID0ge3JhbmdlID0gNjAwLGRhbWFnZSA9IHtkZWZhdWx0ID0gNTAsfSx9LH0sfSx9</code>

== Mass post-processing ==

The above examples deal with specific values for a single unit (e.g. "make Glaive have 500 health").
It is also possible to write Lua code that works on units, including changing values for all units or doing some sort of logic. This time, the option is not "Tweak Units" but "Tweak Defs". Again, it should be encoded to base64.

Here's an example:
<syntaxhighlight lang="lua">for name, ud in pairs(UnitDefs) do
if ud.maxvelocity then
ud.maxvelocity = ud.maxvelocity*10
else
ud.maxdamage = ud.maxdamage*5
end
end</syntaxhighlight>

UnitDefs is a Lua table indexed with unit names as above (for example "cloakraid" for Glaive) whose values are the unit def tables in a similar format as for tweakunits, BUT WITH ALL KEYS LOWERCASE. This snippet increases unit speeds 10 times for all mobiles and health 5 times for all statics. Some fields may be <code>nil</code> (for another example, death explosions are weapons but don't have a reload time). Specific Tweak Units values override the values that result from Tweak Defs.

Happy hacking!

[[File:Zk_1_7_11_0_cover.jpg|frame|center]]

[[Category:Development]]{{Navbox manual}}

Quick Stat Tweaks

2022-02-02T19:54:38Z

Sprung: Update tweak units modoption picture (tweakdefs since added)

The Tweak Units modoption can be used to modify many unit and weapon parameters. It can be used for rapidly testing balance changes or just for making a quick game mode. It has limitations and should not be used for large mod projects, see [[Mod Creation]] and [[How To Play Mods]] to get started on full modding.

[[File:Tweakunitsdefs.png]]

Stat tweaks can be saved and shared as a [[Custom Modes | Custom Mode]].

== Workflow ==
The Tweak Units modoption overwrites unit parameter (called unitDefs) as they are loaded. The modoption requires a base64-encoded Lua array of differences. Here is how to use it.
* Make a Lua table in an empty file.
* For each unit you wish to modify, add an empty table indexed by the [[Internal unit names|internal name]] of the unit to your table.
* Search for the units you wish to modify in the [https://github.com/ZeroK-RTS/Zero-K/blob/master/units Zero-K repository].
* Copy the parameters you wish to modify into the table, maintaining the structure of the unitDef table.
* [https://www.base64encode.org Base64 encode] your table.
* Put the base 64 encoding of your table into the Tweak Units modoption.
* Start the game.
* Check infolog.txt in your install directory and fix your syntax errors.

Check out the [https://springrts.com/wiki/Gamedev:UnitDefs unit def] and [https://springrts.com/wiki/Gamedev:WeaponDefs weapon def] pages on the SpringRTS wiki for definitions of many of the parameters. Search the Internet for tutorials on Lua tables.

== Limitations ==
Tweak Units cannot be used to change parameters that are part of a unit's animation, and access to some of the more unique abilities may be missing. In particular, the aiming speed of most units cannot be changed with this method.

== Simple Example ==
In this example we make Glaive faster and healthier.

Start with an empty Lua table.
<syntaxhighlight lang="lua">{
}</syntaxhighlight>
A search through the [https://github.com/ZeroK-RTS/Zero-K/blob/master/units unitdef repository] reveals that Glaive is known as cloakraid internally. [https://github.com/ZeroK-RTS/Zero-K/blob/master/units/cloakraid.Lua This] is the file. Add an empty table with key 'cloakraid'.
<syntaxhighlight lang="lua">{
cloakraid = {},
}</syntaxhighlight>
The [https://springrts.com/wiki/Gamedev:UnitDefs SpringRTS wiki page on unitdefs] says that a unit's health is 'maxDamage' and its speed is 'maxVelocity'. [https://github.com/ZeroK-RTS/Zero-K/blob/master/units/cloakraid.Lua The Glaive file] shows us the current value of these parameters, as well as their position in the structure of a unitdef. We can change these values like so:
<syntaxhighlight lang="lua">{
cloakraid = {
maxDamage = 500,
maxVelocity = 8,
},
}</syntaxhighlight>
Copy this text into a [https://www.base64encode.org/ base64 encoder] and click encode. Here is the resulting encoding.
<code style="display:block;overflow:auto">ewogICAgY2xvYWtyYWlkID0gewogICAgICAgIG1heERhbWFnZSA9IDUwMCwKICAgICAgICBtYXhWZWxvY2l0eSA9IDgsCiAgICB9LAp9</code>
Set the Tweak Units modoption to your encoding and start the game. Your infolog should indicate that the modoption loaded successfully.
<samp><pre>[f=-000001] Loading UnitDefs_posts
[f=-000001] Loading tweakunits modoption
[f=-000001] Loading tweakunits for cloakraid
[f=-000001] Loading FeatureDefs_posts
[f=-000001] Loading WeaponDefs_posts
[f=-000001] Loading ArmorDefs_posts</pre></samp>

== Advanced Example ==
In this example we will change Bandit's damage and range, and add it to the Glaive changes.

As in the simple example, we find the [https://github.com/ZeroK-RTS/Zero-K/blob/master/units/shieldraid.Lua Bandit's file] and see that it's called shieldraid. To change Bandit and Glaive at the same time, we add a new sub-table to the table from the previous example.
<syntaxhighlight lang="lua">{
cloakraid = {
maxDamage = 500,
maxVelocity = 8,
},
shieldraid = {},
}</syntaxhighlight>
Weapon parameters can be found in the [https://springrts.com/wiki/Gamedev:WeaponDefs SpringRTS page on weapon defs], and Zero-K stores them as a sub-table within unitdefs. The range parameter is inside 'LASER' (the internal name of the Bandit's weapon), which is inside the weaponDefs table of Bandit. Weapon damage is further nested inside the damage sub-table of the weapondef.
<syntaxhighlight lang="lua">{
cloakraid = {
maxDamage = 500,
maxVelocity = 8,
},
shieldraid = {
weaponDefs = {
LASER = {
range = 600,
damage = {
default = 50,
},
},
},
},
}</syntaxhighlight>
As before, we now take this text, [https://www.base64encode.org/ base64 encode] it, and copy it into Tweak Units. Encodings can be shortened by removing whitespace prior to encoding.
<code style="display:block;overflow:auto">e2Nsb2FrcmFpZCA9IHttYXhEYW1hZ2UgPSA1MDAsbWF4VmVsb2NpdHkgPSA4LH0sc2hpZWxkcmFpZCA9IHt3ZWFwb25EZWZzID0ge0xBU0VSID0ge3JhbmdlID0gNjAwLGRhbWFnZSA9IHtkZWZhdWx0ID0gNTAsfSx9LH0sfSx9</code>

== Mass post-processing ==

The above examples deal with specific values for a single unit (e.g. "make Glaive have 500 health").
It is also possible to write Lua code that works on units, including changing values for all units or doing some sort of logic. This time, the option is not "Tweak Units" but "Tweak Defs". Again, it should be encoded to base64.

Here's an example:
<syntaxhighlight lang="lua">for name, ud in pairs(UnitDefs) do
if ud.maxvelocity then
ud.maxvelocity = ud.maxvelocity*10
else
ud.maxdamage = ud.maxdamage*5
end
end</syntaxhighlight>

UnitDefs is a Lua table indexed with unit names as above (for example "cloakraid" for Glaive) whose values are the unit def tables in a similar format as for tweakunits, BUT WITH ALL KEYS LOWERCASE. This snippet increases unit speeds 10 times for all mobiles and health 5 times for all statics. Some fields may be <code>nil</code> (for another example, death explosions are weapons but don't have a reload time). Specific Tweak Units values override the values that result from Tweak Defs.

Happy hacking!

[[File:Zk_1_7_11_0_cover.jpg|frame|center]]

[[Category:Development]]{{Navbox manual}}

File:Tweakunitsdefs.png

2022-02-02T19:53:54Z

Sprung:

Tweak units/defs window

Units

2022-01-19T17:52:09Z

Sprung: Split air into GS and planes; split naval into ships and submarines

The '''Units''' of Zero-K are the tools you will use to execute your strategies and defeat your opponents.

Use your [[Commander]] and [[Unit classes#Constructor|Constructors]] to build up your base and economy, [[Unit classes#Raider|Raider]] and [[Unit classes#Assault|Assault]] units to attack at close range, [[Unit classes#Skirmisher|Skirmishers]] and [[Unit classes#Artillery|Artillery]] to engage at long range, and [[Unit classes#Riot|Riots]] to defend in close quarters.

{| class="wikitable"
! style="text-align: center;" | [[Cloakbot Factory|<img src="http://manual.zero-k.info/unitpics/factorycloak.png" height='64' align="center"/>]]
[[Cloakbot Factory|Cloakbots]]
! style="text-align: center;" | [[Shieldbot Factory|<img src="http://manual.zero-k.info/unitpics/factoryshield.png" height='64' align="center"/>]]
[[Shieldbot Factory|Shieldbots]]
! style="text-align: center;" | [[Rover Assembly|<img src="http://manual.zero-k.info/unitpics/factoryveh.png" height='64' align="center"/>]]
[[Rover Assembly|Rovers]]
! style="text-align: center;" | [[Hovercraft Platform|<img src="http://manual.zero-k.info/unitpics/factoryhover.png" height='64' align="center"/>]]
[[Hovercraft Platform|Hovercraft]]
! style="text-align: center;" | [[Gunship Plant|<img src="http://manual.zero-k.info/unitpics/factorygunship.png" height='64' align="center"/>]]
[[Gunship Plant|Gunships]]
! style="text-align: center;" | [[Airplane Plant|<img src="http://manual.zero-k.info/unitpics/factoryplane.png" height='64' align="center"/>]]
[[Airplane Plant|Airplanes]]
|-
| style="text-align: center; font-weight:bold;" | [[Spider Factory|<img src="http://manual.zero-k.info/unitpics/factoryspider.png" height='64' align="center"/>]]
[[Spider Factory|Spiders]]
| style="text-align: center; font-weight:bold;" | [[Jumpbot Factory|<img src="http://manual.zero-k.info/unitpics/factoryjump.png" height='64' align="center"/>]]
[[Jumpbot Factory|Jumpbots]]
| style="text-align: center; font-weight:bold;" | [[Tank Foundry|<img src="http://manual.zero-k.info/unitpics/factorytank.png" height='64' align="center"/>]]
[[Tank Foundry|Tanks]]
| style="text-align: center; font-weight:bold;" | [[Amphbot Factory|<img src="http://manual.zero-k.info/unitpics/factoryamph.png" height='64' align="center"/>]]
[[Amphbot Factory|Amphbots]]
| style="text-align: center; font-weight:bold;" | [[Shipyard|<img src="http://manual.zero-k.info/unitpics/factoryship.png" height='64' align="center"/>]]
[[Shipyard|Ships]]
| style="text-align: center; font-weight:bold;" | [[Strider Hub|<img src="http://manual.zero-k.info/unitpics/striderhub.png" height='64' align="center"/>]]
[[Strider Hub|Striders]]
|}

Properties shared by most or all units in Zero-K include:

* They cost the same amount of [[Metal]] and [[Energy]].
* Most units are produced by a factory, and autonomous Drones are built by their parent.

Useful information on units:
* [[Unit classes]]
* [[Map icons|Unit map icons]]
* [[Weapon classes]]
* [[Internal unit names]]

==Unit chassis movement traits==

The movement traits of different unit chassis can be a very important factor when choosing which factory to build at the start of a game. Factors such as the terrain of the map as well as the map size can influence this decision. For instance, lots of deep water may call for a factory with lots of amphibious or airborne options, while a map with mostly somewhat steep terrain may call for bots, spiders or airborne options.

===Brief overview===

;Legged chassis
:<img src="http://manual.zero-k.info/unitpics/cloakraid.png" style="float:left;padding-right:0.5em"> ''Bots:'' Non-climbing legged units (generally having two or four legs) tend to have great turn rates and can typically traverse somewhat steep terrain. Some bots are amphibious, notably [[Amphbot Factory|amphbots]] and certain [[Strider Hub|strider bots]]. Some of the bots from the [[Jumpbot Factory]] can jump, which can be useful for traversing terrain as well as in combat.{{clear}}
:<img src="http://manual.zero-k.info/unitpics/cloakbomb.png" style="float:left;padding-right:0.5em">''All-terrain:'' Climbing legged units (generally having four or more legs) can climb and traverse any land terrain, including practically vertical hills and cliffs, but tend to have poor speed. They include [[Spider Factory|all spider factory units]] and various other units such as the [[Scorpion|Scorpion strider]].{{clear}}
;Wheeled, tracked and hovercraft chassis
:<img src="http://manual.zero-k.info/unitpics/vehraid.png" style="float:left;padding-right:0.5em"> [[Rover Assembly|Rovers]] tend to have good or great speed, medium or poor turn rates, and prefer flat terrain (slightly steep terrain slows them).{{clear}}
:<img src="http://manual.zero-k.info/unitpics/tankassault.png" style="float:left;padding-right:0.5em"> [[Tank Foundry|Tanks]] are like rovers, except their speed and turn rates are typically worse.{{clear}}
:<img src="http://manual.zero-k.info/unitpics/hoverraid.png" style="float:left;padding-right:0.5em"> [[Hovercraft Platform|Hovercraft]] are like rovers, except they can traverse water easily.{{clear}}
;Airborne chassis
:<img src="http://manual.zero-k.info/unitpics/bomberriot.png" style="float:left;padding-right:0.5em"> Airplanes fly and tend to have excellent speed. Their movement resembles real-life planes.{{clear}}
:<img src="http://manual.zero-k.info/unitpics/gunshipraid.png" style="float:left;padding-right:0.5em"> Gunships hover above the ground; their movement resembles helicopters.{{clear}}
;Naval chassis
:<img src="http://manual.zero-k.info/unitpics/shipscout.png" style="float:left;padding-right:0.5em"> Ships float on the sea surface. Smaller ships are built in the [[Shipyard]], while carriers and battleships are built at the [[Strider Hub]].{{clear}}
:<img src="http://manual.zero-k.info/unitpics/subraider.png" style="float:left;padding-right:0.5em"> Submarines dive underwater, which gives them protection from radar and weaponry (but they cannot surface).{{clear}}

There are also various kinds of indirect movement, such as transport gunships, teleportation, throwing, gravity projection, etc.

The [[Newbie Guide#Map views|pathing map overlay]] when a unit is selected is useful for viewing where a selected unit can and cannot go.

{{Navbox units}}

{{Navbox buildings}}

[[Category:Units]]

ZK Map Making Guide

2021-10-27T14:47:00Z

Sprung: Add a pic for map blueprint download because github is confusing

Also see:

* [[Map Creation]]
* [https://docs.google.com/document/d/1PL8U2bf-c5HuSVAihdldDTBA5fWKoeHKNb130YDdd-w/edit# Advanced guide using WorldMachine], by Beherith

DISCLAIMER: This guide is a work in progress (particularly with respect to using particular pieces of software) but the basic framework here should give you a good start.

= Minimal Brief Guide =

For more detail on each of these steps read the later sections of the document.

This guide assumes that you are using a version of Zero-K installed through Steam. You can still make maps if you installed by some other method but you may need to modify some of the later steps.

If you want to see what the map's file structure is meant to look like overall, scroll to the [[https://zero-k.info/mediawiki/index.php?title=ZK_Map_Making_Guide#Skeleton_Of_A_Map Skeleton Of A Map]] section. It's also a good idea to un7zip some existing maps and take a look to see how they are set up (and borrow anything which seems useful for your map).

== Download Tools ==

* 7zip - https://www.7-zip.org/download.html
* pymapconv - clone or download https://github.com/Beherith/springrts_smf_compiler somewhere, then copy pymapconv.exe and nvdxt.exe to a new directory to keep things simple
* map blueprint - clone or download https://github.com/Aquanim/ZKMapBlueprint

[[File:Mapguide_download_aquanim_blueprint.png|Map blueprint download]]

== Create Images ==

For a 10x10 (TitanDuel-size) map, create the following images with a tool of your choice:

* A height map grayscale image with dimensions 641 x 641, saved as an 8-bit .bmp or a 16-bit .png. (The latter is preferred but not all tools offer 16-bit output.) The brighter a pixel is the higher the corresponding part of the map will be.
* A texture map colour image with dimensions 5120 x 5120, saved as a .bmp

For a different size map, multiply the height/width of the map by 64 and add 1 to get the right size for the heightmap; multiply the height/width of the map by 512 to get the right size for the texture map.

Different image formats ''might'' work but are just as likely to cause difficult-to-diagnose errors.

Put these images in the same directory as pymapconv.exe from the previous step (may not strictly be required but keeps things simple). 

Useful tools: Spring Map Edit (SME), Springboard, TerreSculptor, World Machine, GIMP, Blender, any image editing software really

== Compile Your Map ==
Run pymapconv.exe and fill in the following fields...
* An output file name - ideally this should be the name of your map, possibly with a version number. File extension .smf, will also generate a .smt. '''IMPORTANT:''' Do not rename these files after compiling!
* Use the buttons to select the texture and heightmap images you made in the previous step.
* I expect the minimum/maximum height values to be overridden by mapinfo.lua later but you might as well set them.
* Scroll down to the NVDXT option and make sure it says "-Sinc -quality_highest". Also probably a good idea to tick the CLEAN option.
* Untick everything else, press "Save options as" if you like, then press the "Compile" button. 

Troubleshooting:
* If your map's minimap looks like it is from an old version of your map or a different map entirely, there is probably an old minimap file which the compiler is reading. In the directory where your compiler .exe is, delete any images which look like a minimap (probably something like mini.bmp and/or mini.dds) then recompile.
* If your map texture looks all pinkish ingame you probably renamed the .smf and .smt files. Regenerate them and be extra sure not to rename them this time. If the issue persists there might be other reasons this can happen, consult the #zkmap channel.

== Construct .sdd File ==
* Rename ZKMapBlueprint_v0.0.sdd to have the name of your map. A version identifier is advisable as well. Keep the .sdd extension.
* Copy the .smf and .smt files produced by pymapconv.exe into the /maps subfolder of the .sdd folder. (There should be mapblueprint.smf and mapblueprint.smt files here, you can delete them.)
* In the root of the .sdd folder there should be a file "mapinfo.lua". Open this with a text editor. This file contains a bunch of stuff but there are only a few items we are interested in for now:
** Near the start of the file change the ''author'', ''description'', ''name'', ''shortname'' and ''version'' variables to suit you and your map.
** Scroll down a bit to the "smf" section and change the ''maxheight'' and ''minheight'' numbers to suit your map. Also change the file name after ''smtFileName0'' so that it has your .smt file's name.
* To test your map, copy the .sdd directory into the /maps folder of your Zero-K install. In the settings make sure that "Only featured maps" is disabled. Then open a Skirmish game, click on the current map, select your map from the list, and play. (You might want to make the enemy AI inactive. The minimap in the lobby will be blank, don't worry about this for now.)
* If you want to change your map you will need to replace the files in your ZK maps folder, then restart ZK, in order to load the new version.

== Metal and Startboxes ==
Now that you can look at your height and texturemap ingame this is a good time to sort out your metal spots and start locations.
=== Metal spots ===
In the /mapconfig subfolder of the .sdd file there is a "map_metal_layout.lua" file. The blueprint contains two metal spots as an example; replace them with your own.

=== Startboxes ===
In the /mapconfig subfolder of the .sdd file there is a "map_startboxes.lua" file. This specifies each team's startboxes as well as default start locations.

Some hints for configuring the metal and startbox files:

* Startboxes are specified by their corner points reading clockwise around the polygon. More than one separate box for a given team is possible.
* Holding SPACE ingame will display a dialog box which (among other things) gives the X and Z coordinates of wherever your cursor is.
* The metal and startbox files are just LUA scripts. This means you don't have to write simple numbers to specify locations; you can perform arithmetic to make sure your map setup is symmetric (the startbox of the South-East team in the blueprint is an example). More advanced scripting is also possible, for example to make your startbox configuration dependent on the number of players or allyteams. See the [[http://zero-k.info/mediawiki/index.php?title=Startbox_API#Advanced_stuff Startbox API page]] .

=== Useful Tools ===

[[https://zero-k.info/mediawiki/index.php?title=ZK_Map_Making_Guide#Startbox_Editor_Widget Startbox Editor Widget]]
[[https://zero-k.info/mediawiki/index.php?title=ZK_Map_Making_Guide#Metal_Spot_Placer Metal Spot Placer]]

== Optional Extras ==
Scroll down to section 3 to see how to add...
* Features (geovents, trees, rocks, etc)
* DNTS (fancy map details and specular map)
* Fancy mapinfo stuff (lighting, water effects, etc)
* Skybox
* Other nonsense (particle effects, sound, etc)
* Lava

== Upload ==

Compress the contents of the .sdd file into a 7z, then change the file extension to “.sd7”.

If you remove the .sdd from your game maps directory and put the .sd7 in its place, the map should still work. It is a good idea to test the .sd7 before uploading since there are several *very* easy mistakes to make in the compression process.

'''IMPORTANT:''' Make sure that when you open the archive you see mapinfo.lua and not your .sdd folder! If you get this wrong the map will not work correctly. If you get an error saying that a .smd file is missing this is probably the problem.

'''IMPORTANT:''' When you compress to 7z make sure the compression is “non-solid”. If using 7zip this is done by setting the "Solid Block size" option to "non solid".

=== Uploading to Zero-K Server ===

* Go to https://zero-k.info/Maps
* Scroll down until you find the "Upload map or game (sd7 or sdz):" file on the right-hand side
* Upload your map
* Test your map on the live server so there is a publically accessible replay or two - games against AIs are fine
* Ask a moderator to support/feature your map (they will also tag it as 1v1/teams/hilly/flat/whatever as appropriate)

If the upload step doesn't work there are two potential reasons:
* Your map isn't set up right. Test it locally again and make sure your map works.
* Something on the server has gone wrong. AFTER testing your map locally and finding that it works there, contact an admin. Uploading your map to a file-sharing service so the admin can look at it may help.

=== Uploading to Springfiles for use in other Spring communities ===

The old Springfiles website is defunct and has been replaced by https://springfiles.springrts.com/?type=0

Somebody who knows how the upload process works now should fill this in. Should hopefully be simpler than old Springfiles though.

= Skeleton Of A Map =

All you *really* need is the stuff in solid grey boxes: mapinfo.lua, .smf and .smt files, a metal layout, and a startbox config.

[[File:Mapskeleton.png|The skeleton of a map]]

(Note: Some of the things labelled as "necessary" probably technically aren't; there are many ways to construct a map that Spring will accept. This guide will walk you through one that should be reasonably coherent and up to date.)

= Tools and Resources =

== Springboard ==

[https://springboard-core.readthedocs.io/en/latest/installing.html Springboard Documentation]

[[Springboard Tutorial]] on this wiki (under construction)

=== Installation ===
[https://github.com/Spring-SpringBoard/SpringBoard-Core/ Github page]
Scroll down to the "Installing" section and get the appropriate installer.

== SpringMapEdit ==

=== Installation ===
[https://springfiles.com/spring/development/spring-map-edit Springfiles page]

== Nobiax Texture Pack ==

== Startbox Editor Widget ==
Load your map in ZK, press Alt-F11 to access the widget list, press "Search" and enter "Startbox". Enable the Startbox Editor widget. The ingame description doesn't say much so let's consult the [https://github.com/ZeroK-RTS/Zero-K/blob/90d61099e3fb8509645cf16d3fa2982150c81bdd/LuaUI/Widgets/dbg_startbox_editor.lua widget source file]:

[[Image:Startboxeditor1.png]]

...well, that's not a good sign. Scroll down a bit further:

[[Image:Startboxeditor2.png]]

That's more like it. Follow those instructions to create your startboxes, then open your infolog.lua (in the main zero-k directory) after you exit to retrieve the startbox information for copying into map_startboxes.lua. It's probably a good idea to turn the widget off after you are done with it.

== Metal Spot Placer ==
Load your map in ZK, press Alt-F11 to access the widget list, press "Search" and enter "Metal Spot". Enable the Metal Spot Placer widget. As per the ingame description:
* Press Alt-M to enable the widget
* Click in locations on the map to place metal points
* Press Alt-M again to disable the widget and print a list of metal points to the infolog

Then open your infolog.lua (in the main zero-k directory) after you exit to retrieve the startbox information for copying into map_metal_layout.lua. Check that the metal point values for each mex point are as you want them to be. It's probably a good idea to turn the widget off after you are done with it.

== Upspring ==

A tool for modifying models like those of tree features, etc. Might be useful if a feature is too large, too small, or not centered properly. I'll leave this guide to somebody who actually understands modelling.

= Other Stuff =

== Features (geovents, trees, rocks, etc) ==

This method of placing features requires you to have some s11n gadgets in /LuaRules/Gadgets and some s11n and lcs stuff in the /libs/ folder. If your map doesn't have these then get them from the blueprint or some other map.

* Put the files defining the features you want in your map file. This includes a definition in the /features subdirectory, model files in the /objects3d directory, and textures in the /unittextures directory. The easiest way to get these is to borrow them from existing maps. There is a features library as well... ask around in #zkmap for a link then update this page.
* Load your map in Springboard
* Delete any features you have marking mex locations, otherwise you will end up with two copies of them and that is bad.
* Place features using Springboard.
* Open the "Export" window in Springboard, choose a file name, set the file type to "s11n object format" and export the file.
* The file will (probably?) have been exported to <springboard exe directory>/data/springboard/exports - copy this s11n file to the ./mapconfig subdirectory of your map.
* Make sure that in ./libs/s11n/s11n_load_map_features.lua that the "modelPath" variable points at your s11n file.

Troubleshooting:
* IF your features do not move when the ground under them is terraformed (a particular problem for geovents) go to ./libs/s11n/features_s11n.lua, look for the "CreateObject" function, and change it so that SetFeatureMoveCtrl is not being used to set MoveCtrl to true.

== DNTS ==

If you don't use DNTS but you do set detailTex in the "resources" section of mapinfo.lua then you will get some general detail map. This works better than flat colour but we can get fancier.

* Put the .dds or .tga files defining the detail map (commonly grass, pebbles, rocks, etc.) you want in your /maps subdirectory. Again these are most easily found by borrowing from other maps. [http://beherith.eat-peet.net/stuff/nobiax_spring_dnts/nobiax_spring_dnts.html This page] has some that may work (possibly with some effort).
* In mapinfo.lua, in the "resources" section, set splatDetailNormalTex1, splatDetailNormalTex2, splatDetailNormalTex3, splatDetailNormalTex4 to point to your detail files. These will in order be defined by the red, green, blue and alpha channels of your distribution image.
* Set splatDistrTex to point to your distribution image. This defines where each detail type appears on your map. This image will be stretched over your map; powers of two in the resolution are advised.
* Set specularTex to point to your specular image; what colour of light will be reflected from each part of the map. It is easy to go overboard with this so taking your texture map, darkening it significantly (or possibly increasing its transparency), and tuning from there is an okay strategy. Again, this image will be stretched over your map; powers of two in the resolution are advised.
* There is also some lightemission thing that I have not used and don't really understand [https://springrts.com/wiki/Mapdev:lightemission here]. The example image looks like Otago so try asking TheMooseIsLoose for advice?

== Water and lighting settings ==

I'm not an expert, tune these for yourself until it looks good. Try reading [https://springrts.com/wiki/Mapdev:water these] [https://springrts.com/wiki/Mapdev:mapinfo.lua#Lighting pages].

== Skybox ==

Borrow one from some other map then set it in mapinfo.lua, atmosphere section, variable "skyBox". If you want to make one yourself apparently pymapconv can put it in the right format.

== Particle and sound effects ==

Find a map that does the thing you want to do, look at how that map did it. For reference some fairly simple examples can be found in Rogues River (sound effects), Aurelian (precipitation), and Mercurial (plumes from the water).

== Lava ==

Good luck... I'm not sure anybody has come up with an entirely bug-free implementation of this yet. Banana Republic might be your best bet for a reference.

{{Navbox manual}} [[Category: Development]]

File:Mapguide download aquanim blueprint.png

2021-10-27T14:45:40Z

Sprung:

== Licensing ==
{{PD}}

Abbreviations

2021-10-14T12:18:24Z

Sprung: AN? Everybody calls anti anti.

===A===
*AA — '''A'''nti '''A'''ir.
*Anti — [[Antinuke|'''Anti'''nuke]].
*Anni — [[Lucifer]] (''anni'' is from Annihilator, the old name) — heavy tachyon tower.
*AoE — '''A'''rea '''o'''f '''E'''ffect (splash damage).
*Avenger — old name for [[Swift]] — multirole fighter.
*Amph — [[Amphbot Factory|'''Amph'''ibious bots]].
*Air — typically indicates [[Airplane Plant|plane factory]] units; rarely [[Gunship Plant|gunships]].
*Arty — short for '''Arti'''llery, a class of long-range units.

===B===
*Bantha — old name for [[Paladin]].
*BB — [[Big Bertha|'''B'''ig '''B'''ertha]] — the long range cannon.
*BD — [[Revenant]], comes from old name Black Dawn — heavy raider/assault gunship.
*Behe — [[Cerberus]], from old name Behemoth.
*BP — buildpower — the speed at which constructors/factories convert resources to units.
*BW — [[Blastwing|'''B'''last'''W'''ing]] — flying bomb unit.

===C===
*CA — Complete Annihilation — ZK's direct ancestor game. Also the Complete Annihilation [[Award|award]] (for dealing the most damage).
*Cata — [[Merlin]]. From the old name, Catapult — artillery strider.
*CCR — [https://zero-k.info/Maps/Detail/55646 Comet Catcher Redux] — the flat vehicle map.
*Chix — [[Chicken Defense]], a Tower Defense style game mode.
*Com(m) — [[Commander|'''Comm'''ander]] — the starting unit.
*Con — [[Unit classes#Constructor|'''Con'''structor]] — any mobile unit with ability to build stuff.
*Cooked — destroyed, usually about players (but sometimes also individual units). See also: [[#lobster|lobster]].
*CS — [[Chainsaw|'''C'''hain'''S'''aw]] — long range anti-air.
*Crow — mistyped [[Krow]].

===D===
*Det — also ''detri'' — [[Detriment]] — the largest strider.
*DDM — [[Desolator]], formerly known as the '''D'''ooms'''d'''ay '''M'''achine — heavy defensive structure.
*DF — DeinFreund — one of the developers.
*Dgun — '''D'''isintegrator '''Gun''' — class of special weapons that need manual activation using "D" key — for example Dante's missile volley or special commander weapons.
*Domi — [[Dominatrix]] — capture vehicle.
*DPS — '''D'''amage '''P'''er '''S'''econd.
*DRP — [[Disco Rave Party|'''D'''isco '''R'''ave '''P'''arty]] — the superweapon.
*Drop — a "drop" happens when units are loaded into transports and then "dropped" somewhere, like the enemy base.
*DSD — [https://zero-k.info/Maps/Detail/56560 Delta Siege Dry] — a popular teams map.

===E===
*E — [[Energy|'''E'''nergy]] — the resource.
*Eco — '''Eco'''nomy — all resource-producing units and buildings.
*Elo — a rating system used for balancing games basing on estimated players skill (on which ZK's ladder ratings used to be based).
*EMP — '''E'''lectro'''M'''agnetic '''P'''ulse — paralyzer weapons, can also be used to mean an air player using [[Thunderbird]].

===F===
*FFA — '''F'''ree '''f'''or '''A'''ll — a match with 3 or more teams.
*Fac — [[Units|'''Fac'''tory]] — building that produces mobile units.
*FW — [[Firewalker]] — artillery bot.
*Fus — [[Fusion Reactor]].
*Firepluk award — named after the player Firepluk; When a player resigns very early into the game but ends up winning anyways.

===G===
*Gaetor — [[Scorcher]], formerly known as Insti'''gator'''.
*Geo — [[Geothermal Generator|'''Geo'''thermal Powerplant]] or the spot where it can be built (also ''geospot'').
*GF — GoogleFrog — one of the lead developers.
*GS — [[Gunship Plant|Gunships]].
*Golly or Goli — [[Cyclops]], formerly known as Goliath — heavy tank.
*Grid — energy grid — system of connected energy sources, part of [[Overdrive|overdrive]]. Structures are in the same grid if their "circles" touch.

===H===
*HLT — '''H'''eavy '''L'''aser '''T'''ower — [[Stinger]].
*Hawk — old name for [[Raptor]] — air superiority fighter.

===I===
*Icy — [https://zero-k.info/Maps/Detail/7513 Icy Run v2], a popular map for (very) high density casual team games.
*IoG — [https://zero-k.info/Maps/Detail/49517 Isle of Grief], a map.

===J===
*JJ — JumpJet Factory, now [[Jumpbot Factory]].

===K===
*KR — KingRaptor — one of the core developers (currently known as Histidine).

===L===
*Licho — old name for [[Likho]] — heavy bomber plane. Also one of the core developers.
*Link — to link disconnected parts of energy grid together OR to link shields together.
*LLT — '''L'''ight '''L'''aser '''T'''ower — the [[Lotus]] turret.
*Lobster — a taunt for a player who hasn't performed well in ongoing or previous battle(s).
*LoS — line of sight.
*LV — '''L'''ight '''V'''ehicles (Factory) — LV got renamed to [[Rover Assembly]].
*Leveler — old name for [[Ripper]].

===M===
*M — [[Metal|'''M'''etal]] — the resource.
*Merl — old name for [[Impaler]].
*Mex — [[Metal Extractor|'''M'''etal '''Ex'''tractor]], ''to mex'' - the action of constructing extractors on untapped metal spots.
*Morph — to upgrade a [[Commander]] or a [[Geothermal Generator]].
*Moho — old name for [[Advanced Geothermal]].
*MT — '''M'''issile '''T'''ower — the [[Picket]] turret.

===N===
*Nano — [[Caretaker]] nanolathe tower — static constructor.
*Nap — to kidnap — usually "comnap" — capture enemy commander with [[Gunship Plant|air transport]].
*NullAI — a "sandbox" skirmish opponent which does nothing, sometimes used as an insult.

===O===
*OD — '''O'''ver'''D'''rive — overdrive pumps spare energy to metal extractors to improve their output, see [[Overdrive|economic section of the manual]].
*OP — '''O'''ver'''P'''owered — something is considered too good for its cost (e.g. a unit/module/ability). Also forum abbreviation for ''original poster'', the person who started the current thread.
*OTA — (Original) Total Annihilation — a 1997 RTS game which ZK started out as a mod of (where "original" is to refer to the retail game as opposed to the collection of the various other mods it spawned).
*Owled — weak enough that it might as well not be in the game.

===P===
*Pene — [[Lance]]. From old name "Penetrator".
*Porc — from porcupine — heavy defenses, usually useless.
*Porcing — playing too defensively, not taking enough land.
*PW — [[PlanetWars|'''P'''lanet'''W'''ars]] — the online multiplayer campaign.
*Plop (fac) — deploying your first factory, which is free and builds instantly.

===R===
*Rec — [[Reclaim Command|'''Rec'''laim]] — command to recycle units, wreckages and map features.
*Ress/rez — [[Resurrect Command|'''Ress'''urection]] (common misspelled version of resurrection) — ability to recreate a unit from its wreckage.
*Reaper — old name for [[Minotaur]].

===S===
*SD — [[Stardust|'''S'''tar'''d'''ust]].
*Singu — [[Singularity Reactor|'''Singu'''larity Reactor]] — most powerful, and most dangerous energy-producing structure.
*Shadow — old name for [[Raven]] — bomber plane.
*Shiny — huge explosion caused either by nuke, advanced geothermal or destruction of Singularity Reactor. Can also be used when a lot of bombs chain explode.
*Skydust — [[Stardust]] on a [[Terraform|terraformed]] spire.
*Starlulz — [[Starlight]].
*Stiletto — old name for [[Thunderbird]].
*Sumo — old name for [[Jugglenaut]].
*SSB — [https://zero-k.info/Maps/Detail/7770 Small Supreme Battlefield] — a remake of Seton's Clutch, the iconic map from Supreme Commander.
*Selfd — '''Self D'''estruct — usually meant as an encouragement to self destruct all your things using CTRL+A, CTRL+D keys to end the game; sometimes to self destruct a single unit for its powerful death explosion.
*Shield-ball — a group of units that have shields, usually containing [[Thug]]s, [[Felon]]s, and possibly an [[Aspis]].
*Stealth — also 'stealth-ball' — a group of units with personal cloaks (like [[Scythe]]s, or under cloaking field of [[Aspis]].

===T===
*TB — [[Thunderbird|'''T'''hunder'''b'''ird]] — area disable bomber plane.
*Terra — [[Terraform|'''Terra'''form]] — a way to modify map's landscape.
*Tit d — [https://zero-k.info/Maps/Detail/56655 Titan Duel], a popular map.
*Trollcom — a frontline [[Commander]] with a lot of investment, typically a disintegrator gun commander with high movement speed and stealth cloak.
*Tick — old name for [[Imp]].

===U===
*Ubermex — a [[Metal Extractor]] spot with much more yield than usual (4+ while typical mex is 2).
*UP — '''U'''nder'''P'''owered — something is considered too weak for its cost (e.g. a unit/module/ability).
*Ulti — [[Ultimatum|'''Ulti'''matum]] — cloaked anti-heavy strider.

===V===
*Vamp — old name for [[Raptor]] — air superiority fighter.
*Vindi — [[Hercules]]. From the old name Vindicator.

===W===
*Warrior — old name for [[Reaver]].
*WHR — Whole History Rating — the rating system used for the ZK ladder. See also: [[#Elo|Elo]].
*Wubbernaut — a new player. Comes from ''wub'' (similar to nub) + ''naut'' (to explore).

===Z===
*ZK — [[Zero Kelvin|'''Z'''ero '''K'''elvin]] — the name of this game.

{{Navbox manual}}

Resurrect Command

2021-10-14T12:11:49Z

Sprung: Engineer comm is multiplayer; misc tweaks

An alternative to [[Reclaim]], resurrection is a late-game option that allows players to resurrect wrecks of units and buildings. Only [[Athena]]s and [[Commander|Commanders]] with the [[Commander#Support|Lazarus Device]] (which in multiplayer requires the Engineer chassis) are able to resurrect units. The default hotkey is {{key press|T}}.

The case for resurrection comes up mostly at the [[typical game progression|later stages of the game]], as it requires copious amounts of [[Energy]]. While [[Reclaim]] grants you 40% of wreck's metal cost, with resurrection you need to pay 200% of its value in Energy in order to restore it. In late game, however, Energy is generally abundant, and an ability to reassemble valuable units, armies or defensive lines for no [[Metal]] payment is invaluable.

In conclusion:
*Resurrection takes 200% of target's cost in Energy and returns 100% of its Metal cost by fully reviving it.
*Reclaim takes 0% Energy directly (though you will later need Energy to use the resulting Metal) and returns 40% of its Metal cost back into your pocket.
*Resurrection can take effect only on [[wreck]]s. Self-destruction, large explosions, [[Ultimatum]]'s gun and any other weaponry inflicting large amounts of burst damage will render the target unresurrectable.
**As such, debris is useless for resurrections and should be reclaimed.
*Resurrection takes quite a bit longer than reclaim. Also, if a unit was partially reclaimed earlier, you will need to refill its Metal wreck beforehand.
*Resurrection is best used late in the game, with abundance of Energy, to quickly replenish your forces, or even to take dead enemies to fight for you.

{{Navbox commands}}
[[Category: Commands]]

Corpses

2021-10-13T14:31:39Z

Sprung: Redirected page to Wreckage

#REDIRECT [[Wreckage]]

Corpse

2021-10-13T14:31:26Z

Sprung: Redirected page to Wreckage

#REDIRECT [[Wreckage]]

Resurrect Command

2021-10-13T12:16:31Z

Sprung: Reclaim costs no E directly, severity is not health*2

An alternative to [[Reclaim]], resurrection is a late-game option that allows players to resurrect wrecks of units and buildings. Only [[Athena]]s and [[Commander|Engineer Commander]] with [[Commander#Support|Lazarus Device]] are able to resurrect units. Default accelerator key is {{key press|T}}.

The case for resurrection comes up mostly at the [[typical game progression|later stages of the game]], as it requires copious amounts of energy. While [[Reclaim]] grants you 40% of wreck's cost, with resurrection you need to pay 200% of its value in energy in order to restore it. In late game, however, energy is generally abundant, and an ability reassemble valuable units, armies or defensive lines for no metal payment is invaluable.

In conclusion:

*Resurrection takes 200% of target's cost in energy and returns 100% of its metal cost by fully reviving it.

*Reclaim takes 0% energy directly (though you will later need energy to use the resulting metal) and returns 40% of its metal cost back into your pocket.

*Resurrection can only take affect on [[wreck]]s. Self-destruction, large explosions, [[Ultimatum]]'s gun and any other weaponry inflicting large amounts of burst damage will render the target unresurrectable.

*As such, debris is useless for resurrections, and should be reclaimed.

*Resurrection takes quite a bit longer then reclaim. Also, if a unit was partially reclaimed earlier, you will need to refill its metal wreck beforehand.

*Resurrection is best used late-game, with abundance of energy, to quickly replenish your forces, or even take dead enemies to fight for you.

{{Navbox commands}}
[[Category: Commands]]

Wreckage

2021-10-13T12:12:32Z

Sprung: Fix list formatting

Wrecks are objects that drop from units upon deaths. If the unit suffers a lot of damage in a short period of time, it turns into debris instead. Wrecks can be reclaimed for metal, creating a dynamic point of interest on the map (for battles in the field) and providing a bit of defender's advantage.

=== Wrecks ===
* reclaim for 40% of unit's cost.
* can be resurrected by Athena or a Commander with the Lazarus Device module, for 200% of the original unit's cost, but in energy only.
* has the same health as the base unit, and turns into debris if destroyed (but overkill damage doesn't carry over).
* often blocks unit pathing and building construction, except for very small units.
* large units can crush small wreckage by moving over them, turning them into debris.

=== Debris ===
* reclaim for 20% of unit's cost.
* can NOT be resurrected.
* has the same health as the base unit, disappears completely if destroyed.
* does not block pathing or construction.
* units always turn into debris when self-destructed. This is useful if you cannot retrieve a high-value unit that is close to death, and would rather not give your enemy as much of an economic boost.

=== Shards ===
* only created from commander module wrecks, around the commander's wreck (the main wreck is left "naked").
* can NOT be resurrected or collected by a commander, only reclaimed. A resurrected commander starts with no modules.
* have 40% of the module's metal value and their health is 200% of the cost (e.g. a 100m module has 40m reclaim and 200 health).
* turn into debris when destroyed, which have 20% of the value but otherwise are the same.

= Detailed mechanics =

Whether a unit turns into a wreck or debris is controlled by the "severity" of its death. Units leave a full wreck if the severity value is less than 50% of their max health, debris otherwise. Severity is a numerical buffer that accumulates damage taken by the unit and dissipates 10% of its value every simulation frame (or, equivalently, 95% every second). The way this resolves is that its value will be approximately the last damage instance, unless under heavy concentrated fire, and continuous weapons such as Lotus will leave the value at about 1/3 of their DPS (so a 75 DPS laser usually kills units with 25 severity). In practice this means that burst, high-alpha damage is far better at turning units into debris than continuous damage.

Wreckage

2021-10-13T12:12:00Z

Sprung: Details etc

Scrap

2021-10-13T11:50:19Z

Sprung: Redirected page to Wreckage

#REDIRECT [[Wreckage]]

Debris

2021-10-13T11:48:18Z

Sprung: Redirected page to Wreckage

#REDIRECT [[Wreckage]]

Wrecks

2021-10-13T11:48:02Z

Sprung: Redirected page to Wreckage

#REDIRECT [[Wreckage]]

Wreckage

2021-10-13T11:47:37Z

Sprung: Sprung moved page Wreck to Wreckage

Wrecks are objects that drop from units upon deaths. If the unit suffers damage twice it's health, it turns into debris. If the unit dies at any lower damage, it turns into a wreck.
* Wrecks reclaim for 40% of unit's cost.
* Debris reclaims for 20% of unit's cost.
Upon self-destruction, unit turns into debris at all times. This is useful if you cannot retrieve a high-value unit that is close to death, and would rather not give your enemy as much of an economic boost.

Wreck

2021-10-13T11:47:37Z

Sprung: Sprung moved page Wreck to Wreckage

#REDIRECT [[Wreckage]]

Burning

2021-10-05T17:57:09Z

Sprung: Redirected page to Fire

#REDIRECT [[Fire]]

Afterburn

2021-10-05T17:56:57Z

Sprung: Afterburn -> Fire

#REDIRECT [[Fire]]

Napalm

2021-10-05T17:56:38Z

Sprung: Napalm -> Fire

#REDIRECT [[Fire]]

Status Effects

2021-10-05T17:52:29Z

Sprung:

Zero-K has a lot of status effects, special debuffs that can be applied to enemy units to help suppress them and support your armies in battle. They work by filling separate damage meters underneath the target's hit points, and generate various effects.<div style="float:right;">__TOC__</div>

== EMP damage ==
EMP damage stuns enemies, completely disabling them and preventing them from moving, using abilities, or returning fire.

[[File:Weapon EMP.jpg]]

* When an instance of EMP damage is applied to an enemy, it is checked in proportion to the enemy's current health and converted into a stacking percentage.
* When EMP percentage reaches 100% or higher, the unit is stunned.
* EMP percentage on units decay at a rate of 2.5% per second. The moment the unit's percentage drops below 100%, it is no longer stunned.
* Even though EMP percentage stacks, it doesn't stack freely: every EMP weapon has a maximum percentage it can raise a unit to. This is described in the weapon stat block as a maximum stun time - each second effectively being a 2.5% maximum over 100% since EMP decays at that rate.
** For example, a [[Venom]] has a maximum stun time of 1s, which means it can at most raise an enemy's stun percentage to 102.5%.
** Meanwhile a [[Widow]] can stun a unit for 30s, which means it can raise an enemy's stun percentage to 100 + 30 * 2.5 = 175%.

Against shields, EMP damage is divided by 3 and converted into normal shield damage. If a weapon deals normal and EMP damage together, the EMP damage is applied last.

EMP is yellow, or in the case of the self-destructing [[Imp]], blue.

== Disarm damage ==
Disarm is a particular type of EMP that will leave the afflicted units able to move, but unable to use any weapons or special abilities (this includes jumping, using build power, regeneration or receiving income from the commander's Vanguard economy module). Disarm damage is converted into a separate disarm percentage bar tracked independently from EMP percentage. Disarmed units flash yellow instead of blue.

== Slow damage ==
Slow damage gradually decreases the movement speed and rate of fire of enemy units.

[[File: Weapon slow.jpg]]

* Unlike EMP or disarm damage, slow damage is tracked and stored directly on the affected unit as a total rather than being converted into a percentage.
* As long as a unit has slow damage on it, it's slowed in proportion to the slow damage / its maximum health. This means that damaging a unit can increase its slow since the slow damage buffer becomes proportionally larger.
* Slow damage is always capped at 50% of the unit's current health. If a unit is damaged to the point that slow damage would rise over this limit, the extra slow damage is cleared.
* After 0.5s of taking no slow damage, units start clearing slow damage = 4% of their current health per second.
* Some units (the [[Limpet]] and [[Moderator]]) apply '''overslow''':
** This is a secondary status effect that raises the slow damage cap of the target to a higher percentage than 50%.
** Even when a unit's slow damage is higher than 50% of its current health thanks to overslow, it is still only slowed down by 50%. Overslow can only "stretch out" a 50% slow longer.
** Overslow is tracked and cleared separately from slow.

Like EMP damage, slow damage is divided by 3 and converted into normal damage against shields.

Slow is purple.

== Capture damage ==
Capture damage is a special kind of damage only dealt by the [[Dominatrix]]. It can steal a unit from an enemy and place it under your (potentially permanent) control.

* When an instance of capture damage is applied to an enemy, it is directly converted into a percentage just like with EMP damage. Unlike with EMP damage, it's divided by (the target enemy's current HP + 1000) instead of just the target's current HP.
* When a unit reaches 100% capture percentage, it is captured and belongs to the Dominatrix's player. It stays this way until the Dominatrix that dealt the final instance of capture damage is destroyed or the unit is captured by a different Dominatrix.
* After 5s of taking no capture damage, capture percentage decays at a rate of 4% per second.
* If a captured unit's controlling Dominatrix is destroyed, it is returned to its original controller with 95% capture percentage.
* Capturing a Dominatrix grants control of it as well as its subordinates. Battles with Dominatrices on both side can result in a tree-like control structure.
* Capturing a unit that originally belonged to an ally returns it to that ally without creating a control link.
* Even though capture percentage stacks, it does not stack between players who belong on different teams (say, in a 3 player FFA). Each team gets their own capture bar for the target unit, and the UI will only display the highest percentage.

When a unit is captured, a yellow line is displayed connecting them to their controlling Dominatrix, visible if either the Dominatrix or the unit is visible.

Moderator

2021-10-05T16:50:04Z

Sprung: Wording (overslow doesnt actually slow more, just longer)

The '''{{PAGENAME}}''' is a disruptor skirmisher walker from the [[Jumpbot Factory]].{{ Infobox zkunit
| name = Moderator
| defname = jumpskirm
| description = Disruptor Skirmisher Walker
| image = http://manual.zero-k.info/unitpics/jumpskirm.png
| icontype = fatbotsupport
| cost = 240
| hitpoints = 480
| movespeed = 57
| turnrate = 475
| sight = 473
| transportable = Light
| weapons =
{{ Infobox zkweapon
| name = Disruptor Pulse Beam
| type = BeamLaser
| damage = 460
| reloadtime = 10
| dps = 46
| slowdamage = 1840
| slowdps = 184
| range = 420
| special1 = Instantly hits
}}
| abilities =
{{ Infobox zkability line
| customdata1 = Can ignore unidentified targets
}}
}}==Description==
The Moderator's disruptor beam reduces enemy speed and rate of fire by up to 50% in addition to dealing damage, making it effective against almost all targets.

== Tactics and Strategy ==
Since the Moderator's slowbeam instantly hits, and since it deals significant amounts of slow damage, even high-weight raiders such as the [[Blitz]] and [[Pyro]] are ill-suited towards dealing with about equal numbers of Moderators. To counter this, try switching to using cheaper, smaller raiders like [[Glaive]]s, or longer-ranged skirmishers like [[Ronin]]s or [[Fencer]]s.

== Mechanics ==
Not only does the Moderator slow, it also overslows - the targeted enemy unit can take extra slow damage, equivalent to 2 seconds of decay, above the usual cap, though without actually increasing the slowdown (this means staying at the maximum 50% slowdown for 2 seconds instead of falling off immediately, as long as enough slow damage was dealt).

{{Navbox units}}

Limpet

2021-10-05T16:41:54Z

Sprung: Wording (overslow doesnt actually slow more, just longer)

The '''{{PAGENAME}}''' is an amphibious slow bomb from the [[Amphbot Factory]].{{ Infobox zkunit
| name = Limpet
| defname = amphbomb
| description = Amphibious Slow Bomb
| image = http://manual.zero-k.info/unitpics/amphbomb.png
| icontype = amphbomb
| cost = 150
| hitpoints = 400
| movespeed = 123
| turnrate = 593
| sight = 240
| sonar = 240
| transportable = Light
| weapons =
{{ Infobox zkweapon
| name = Slowing Explosion
| damage = 150
| slowdamage = 1201
| slowdps = 0
| aoe = 250
| special1 = No friendly fire
}}
| abilities =
{{ Infobox zkability regen
| waterregen = 10
| atdepth = 30
}}
{{ Infobox zkability line
| customdata1 = Instant self-destruction
}}
}}==Description==
The Limpet can dodge most slow projectiles thanks to its agility and small size, allowing it to get close to enemy units in order to detonate, slowing and damaging them. Unlike other types of bombs, friendly units are not affected by its explosion.

==Mechanics==
Not only does the Limpet slow, it also overslows - every enemy unit caught in the blast can take extra slow damage, equivalent to 5 seconds of decay, above the usual cap, though without actually increasing the slowdown (this means staying at the maximum 50% slowdown for 5 seconds instead of falling off immediately, as long as enough slow damage was dealt).

{{Navbox units}}

Quick Stat Tweaks

2021-08-18T12:28:29Z

Sprung:

The Tweak Units modoption can be used to modify many unit and weapon parameters. It can be used for rapidly testing balance changes or just for making a quick game mode. It has limitations and should not be used for large mod projects, see [[Mod Creation]] and [[How To Play Mods]] to get started on full modding.

[[File:Tweakunitswindow.jpg]]

Stat tweaks can be saved and shared as a [[Custom Modes | Custom Mode]].

== Workflow ==
The Tweak Units modoption overwrites unit parameter (called unitDefs) as they are loaded. The modoption requires a base64 encoded lua array of differences. Here is how to use it.
* Make a lua table in an empty file.
* For each unit you wish to modify, add an empty table indexed by the internal name of the unit to your table.
* Search for the units you wish to modify in the [https://github.com/ZeroK-RTS/Zero-K/blob/master/units Zero-K repository].
* Copy the parameters you wish to modify into the table, maintaining the structure of the unitDef table.
* [https://www.base64encode.org Base64 encode] your table.
* Put the base 64 encoding of your table into the Tweak Units modoption.
* Start the game.
* Check infolog.txt in your install directory and fix your syntax errors.

Check out the [https://springrts.com/wiki/Gamedev:UnitDefs unit def] and [https://springrts.com/wiki/Gamedev:WeaponDefs weapon def] pages on the SpringRTS wiki for definitions of many of the parameters. Search the internet for tutorials on lua tables.

== Limitations ==
Tweak Units cannot be used to change parameters that are part of a unit's animation, and access to some of the more unique abilities may be missing. In particular, the aiming speed of most units cannot be changed with this method.

== Simple Example ==
In this example we make Glaive faster and healthier.

Start with an empty lua table.
<nowiki>{
}</nowiki>
A search through the [https://github.com/ZeroK-RTS/Zero-K/blob/master/units unitdef repository] reveals that Glaive is known as cloakraid internally. [https://github.com/ZeroK-RTS/Zero-K/blob/master/units/cloakraid.lua This] is the file. Add an empty table with key 'cloakraid'.
<nowiki>{
cloakraid = {},
}</nowiki>
The [https://springrts.com/wiki/Gamedev:UnitDefs SpringRTS wiki page on unitdefs] says that a unit's health is 'maxDamage' and its speed is 'maxVelocity'. [https://github.com/ZeroK-RTS/Zero-K/blob/master/units/cloakraid.lua The Glaive file] shows us the current value of these parameters, as well as their position in the structure of a unitdef. We can change these values like so:
<nowiki>{
cloakraid = {
maxDamage = 500,
maxVelocity = 8,
},
}</nowiki>
Copy this text into a [https://www.base64encode.org/ base64 encoder] and click encode. Here is the resulting encoding.
ewogICAgY2xvYWtyYWlkID0gewogICAgICAgIG1heERhbWFnZSA9IDUwMCwKICAgICAgICBtYXhWZWxvY2l0eSA9IDgsCiAgICB9LAp9
Set the Tweak Units modoption to your encoding and start the game. Your infolog should indicate that the modoption loaded successfully.
<nowiki>[f=-000001] Loading UnitDefs_posts
[f=-000001] Loading tweakunits modoption
[f=-000001] Loading tweakunits for cloakraid
[f=-000001] Loading FeatureDefs_posts
[f=-000001] Loading WeaponDefs_posts
[f=-000001] Loading ArmorDefs_posts</nowiki>

== Advanced Example ==
In this example we will change Bandit's damage and range, and add it to the Glaive changes.

As in the simple example, we find the [https://github.com/ZeroK-RTS/Zero-K/blob/master/units/shieldraid.lua Bandit's file] and see that it called shieldraid. To change Bandit and Glaive at the same time we add a new subtable to the table from the previous example.
<nowiki>{
cloakraid = {
maxDamage = 500,
maxVelocity = 8,
},
shieldraid = {},
}</nowiki>
Weapon parameters can be found in the [https://springrts.com/wiki/Gamedev:WeaponDefs SpringRTS page on weapon defs], and Zero-K stores them as a subtable within unitdefs. The range parameter is inside 'LASER' (the internal name of the Bandit's weapon), which is inside the weaponDefs table of Bandit. Weapon damage is further nested inside the damage sub-table of the weapondef.
<nowiki>{
cloakraid = {
maxDamage = 500,
maxVelocity = 8,
},
shieldraid = {
weaponDefs = {
LASER = {
range = 600,
damage = {
default = 50,
},
},
},
},
}</nowiki>
As before, we now take this text, [https://www.base64encode.org/ base64 encode] it, and copy it into Tweak Units. Encodings can be shortened by removing whitespace prior to encoding.
<pre style="display:block;overflow:auto">e2Nsb2FrcmFpZCA9IHttYXhEYW1hZ2UgPSA1MDAsbWF4VmVsb2NpdHkgPSA4LH0sc2hpZWxkcmFpZCA9IHt3ZWFwb25EZWZzID0ge0xBU0VSID0ge3JhbmdlID0gNjAwLGRhbWFnZSA9IHtkZWZhdWx0ID0gNTAsfSx9LH0sfSx9</pre>

== Mass post-processing ==

The above example deal with specific values for a single unit (e.g. "make Glaive have 500 health").
It is also possible to write Lua code that works on units, including changing values for all units or doing some sort of logic. This time, the option is not "Tweak Units" but "Tweak Defs". Again, it should be encoded to base64.

Here's an example:
<nowiki>for name, ud in pairs(UnitDefs) do
if ud.maxvelocity then
ud.maxvelocity = ud.maxvelocity*10
else
ud.maxdamage = ud.maxdamage*5
end
end</nowiki>

UnitDefs is a Lua table indexed with unit names as above (for example "cloakraid" for Glaive) whose values are the unit def tables in a similar format as for tweakunits, BUT WITH ALL KEYS LOWERCASE. This snippet increases unit speeds 10 times for all mobiles and health 5 times for all statics. Pay attention that some fields may be nil (for another example, death explosions are weapons but don't have a reload time). Specific Tweak Units values override the values that result from Tweak Defs.

Happy hacking!

[[File:Zk_1_7_11_0_cover.jpg|frame|center]]

[[Category:Development]]{{Navbox manual}}

Quick Stat Tweaks

2021-08-18T12:15:10Z

Sprung:

The Tweak Units modoption can be used to modify many unit and weapon parameters. It can be used for rapidly testing balance changes or just for making a quick game mode. It has limitations and should not be used for large mod projects, see [[Mod Creation]] and [[How To Play Mods]] to get started on full modding.

[[File:Tweakunitswindow.jpg]]

Stat tweaks can be saved and shared as a [[Custom Modes | Custom Mode]].

== Workflow ==
The Tweak Units modoption overwrites unit parameter (called unitDefs) as they are loaded. The modoption requires a base64 encoded lua array of differences. Here is how to use it.
* Make a lua table in an empty file.
* For each unit you wish to modify, add an empty table indexed by the internal name of the unit to your table.
* Search for the units you wish to modify in the [https://github.com/ZeroK-RTS/Zero-K/blob/master/units Zero-K repository].
* Copy the parameters you wish to modify into the table, maintaining the structure of the unitDef table.
* [https://www.base64encode.org Base64 encode] your table.
* Put the base 64 encoding of your table into the Tweak Units modoption.
* Start the game.
* Check infolog.txt in your install directory and fix your syntax errors.

Check out the [https://springrts.com/wiki/Gamedev:UnitDefs unit def] and [https://springrts.com/wiki/Gamedev:WeaponDefs weapon def] pages on the SpringRTS wiki for definitions of many of the parameters. Search the internet for tutorials on lua tables.

== Limitations ==
Tweak Units cannot be used to change parameters that are part of a unit's animation, and access to some of the more unique abilities may be missing. In particular, the aiming speed of most units cannot be changed with this method.

== Simple Example ==
In this example we make Glaive faster and healthier.

Start with an empty lua table.
<nowiki>{
}</nowiki>
A search through the [https://github.com/ZeroK-RTS/Zero-K/blob/master/units unitdef repository] reveals that Glaive is known as cloakraid internally. [https://github.com/ZeroK-RTS/Zero-K/blob/master/units/cloakraid.lua This] is the file. Add an empty table with key 'cloakraid'.
<nowiki>{
cloakraid = {},
}</nowiki>
The [https://springrts.com/wiki/Gamedev:UnitDefs SpringRTS wiki page on unitdefs] says that a unit's health is 'maxDamage' and its speed is 'maxVelocity'. [https://github.com/ZeroK-RTS/Zero-K/blob/master/units/cloakraid.lua The Glaive file] shows us the current value of these parameters, as well as their position in the structure of a unitdef. We can change these values like so:
<nowiki>{
cloakraid = {
maxDamage = 500,
maxVelocity = 8,
},
}</nowiki>
Copy this text into a [https://www.base64encode.org/ base64 encoder] and click encode. Here is the resulting encoding.
ewogICAgY2xvYWtyYWlkID0gewogICAgICAgIG1heERhbWFnZSA9IDUwMCwKICAgICAgICBtYXhWZWxvY2l0eSA9IDgsCiAgICB9LAp9
Set the Tweak Units modoption to your encoding and start the game. Your infolog should indicate that the modoption loaded successfully.
<nowiki>[f=-000001] Loading UnitDefs_posts
[f=-000001] Loading tweakunits modoption
[f=-000001] Loading tweakunits for cloakraid
[f=-000001] Loading FeatureDefs_posts
[f=-000001] Loading WeaponDefs_posts
[f=-000001] Loading ArmorDefs_posts</nowiki>

== Advanced Example ==
In this example we will change Bandit's damage and range, and add it to the Glaive changes.

As in the simple example, we find the [https://github.com/ZeroK-RTS/Zero-K/blob/master/units/shieldraid.lua Bandit's file] and see that it called shieldraid. To change Bandit and Glaive at the same time we add a new subtable to the table from the previous example.
<nowiki>{
cloakraid = {
maxDamage = 500,
maxVelocity = 8,
},
shieldraid = {},
}</nowiki>
Weapon parameters can be found in the [https://springrts.com/wiki/Gamedev:WeaponDefs SpringRTS page on weapon defs], and Zero-K stores them as a subtable within unitdefs. The range parameter is inside 'LASER' (the internal name of the Bandit's weapon), which is inside the weaponDefs table of Bandit. Weapon damage is further nested inside the damage sub-table of the weapondef.
<nowiki>{
cloakraid = {
maxDamage = 500,
maxVelocity = 8,
},
shieldraid = {
weaponDefs = {
LASER = {
range = 600,
damage = {
default = 50,
},
},
},
},
}</nowiki>
As before, we now take this text, [https://www.base64encode.org/ base64 encode] it, and copy it into Tweak Units. Encodings can be shortened by removing whitespace prior to encoding.
<pre style="display:block;overflow:auto">e2Nsb2FrcmFpZCA9IHttYXhEYW1hZ2UgPSA1MDAsbWF4VmVsb2NpdHkgPSA4LH0sc2hpZWxkcmFpZCA9IHt3ZWFwb25EZWZzID0ge0xBU0VSID0ge3JhbmdlID0gNjAwLGRhbWFnZSA9IHtkZWZhdWx0ID0gNTAsfSx9LH0sfSx9</pre>

== Mass post-processing ==

The above example deal with specific values for a single unit (e.g. "make Glaive have 500 health").
It is also possible to write Lua code that works on units, including changing values for all units or doing some sort of logic. This time, the option is not "Tweak Units" but "Tweak Defs". Again, it should be encoded to base64.

Here's an example:
<nowiki>for name, ud in pairs(UnitDefs) do
if ud.maxvelocity then
ud.maxvelocity = ud.maxvelocity*10
else
ud.maxdamage = ud.maxdamage*5
end
end</nowiki>

UnitDefs is a Lua table indexed with unit names as above (for example "cloakraid" for Glaive) whose values are the unit def tables in a similar format as for tweakunits, BUT WILL ALL KEYS LOWERCASE. This snippet increases unit speeds 10 times for all mobiles and health 5 times for all statics. Pay attention that some fields may be nil (for another example, death explosions are weapons but don't have a reload time). Specific Tweak Units values override the values that result from Tweak Defs.

Happy hacking!

[[File:Zk_1_7_11_0_cover.jpg|frame|center]]

[[Category:Development]]{{Navbox manual}}

Quick Stat Tweaks

2021-08-18T12:09:22Z

Sprung: Add tweakdefs

The Tweak Units modoption can be used to modify many unit and weapon parameters. It can be used for rapidly testing balance changes or just for making a quick game mode. It has limitations and should not be used for large mod projects, see [[Mod Creation]] and [[How To Play Mods]] to get started on full modding.

[[File:Tweakunitswindow.jpg]]

Stat tweaks can be saved and shared as a [[Custom Modes | Custom Mode]].

== Workflow ==
The Tweak Units modoption overwrites unit parameter (called unitDefs) as they are loaded. The modoption requires a base64 encoded lua array of differences. Here is how to use it.
* Make a lua table in an empty file.
* For each unit you wish to modify, add an empty table indexed by the internal name of the unit to your table.
* Search for the units you wish to modify in the [https://github.com/ZeroK-RTS/Zero-K/blob/master/units Zero-K repository].
* Copy the parameters you wish to modify into the table, maintaining the structure of the unitDef table.
* [https://www.base64encode.org Base64 encode] your table.
* Put the base 64 encoding of your table into the Tweak Units modoption.
* Start the game.
* Check infolog.txt in your install directory and fix your syntax errors.

Check out the [https://springrts.com/wiki/Gamedev:UnitDefs unit def] and [https://springrts.com/wiki/Gamedev:WeaponDefs weapon def] pages on the SpringRTS wiki for definitions of many of the parameters. Search the internet for tutorials on lua tables.

== Limitations ==
Tweak Units cannot be used to change parameters that are part of a unit's animation, and access to some of the more unique abilities may be missing. In particular, the aiming speed of most units cannot be changed with this method.

== Simple Example ==
In this example we make Glaive faster and healthier.

Start with an empty lua table.
<nowiki>{
}</nowiki>
A search through the [https://github.com/ZeroK-RTS/Zero-K/blob/master/units unitdef repository] reveals that Glaive is known as cloakraid internally. [https://github.com/ZeroK-RTS/Zero-K/blob/master/units/cloakraid.lua This] is the file. Add an empty table with key 'cloakraid'.
<nowiki>{
cloakraid = {},
}</nowiki>
The [https://springrts.com/wiki/Gamedev:UnitDefs SpringRTS wiki page on unitdefs] says that a unit's health is 'maxDamage' and its speed is 'maxVelocity'. [https://github.com/ZeroK-RTS/Zero-K/blob/master/units/cloakraid.lua The Glaive file] shows us the current value of these parameters, as well as their position in the structure of a unitdef. We can change these values like so:
<nowiki>{
cloakraid = {
maxDamage = 500,
maxVelocity = 8,
},
}</nowiki>
Copy this text into a [https://www.base64encode.org/ base64 encoder] and click encode. Here is the resulting encoding.
ewogICAgY2xvYWtyYWlkID0gewogICAgICAgIG1heERhbWFnZSA9IDUwMCwKICAgICAgICBtYXhWZWxvY2l0eSA9IDgsCiAgICB9LAp9
Set the Tweak Units modoption to your encoding and start the game. Your infolog should indicate that the modoption loaded successfully.
<nowiki>[f=-000001] Loading UnitDefs_posts
[f=-000001] Loading tweakunits modoption
[f=-000001] Loading tweakunits for cloakraid
[f=-000001] Loading FeatureDefs_posts
[f=-000001] Loading WeaponDefs_posts
[f=-000001] Loading ArmorDefs_posts</nowiki>

== Advanced Example ==
In this example we will change Bandit's damage and range, and add it to the Glaive changes.

As in the simple example, we find the [https://github.com/ZeroK-RTS/Zero-K/blob/master/units/shieldraid.lua Bandit's file] and see that it called shieldraid. To change Bandit and Glaive at the same time we add a new subtable to the table from the previous example.
<nowiki>{
cloakraid = {
maxDamage = 500,
maxVelocity = 8,
},
shieldraid = {},
}</nowiki>
Weapon parameters can be found in the [https://springrts.com/wiki/Gamedev:WeaponDefs SpringRTS page on weapon defs], and Zero-K stores them as a subtable within unitdefs. The range parameter is inside 'LASER' (the internal name of the Bandit's weapon), which is inside the weaponDefs table of Bandit. Weapon damage is further nested inside the damage sub-table of the weapondef.
<nowiki>{
cloakraid = {
maxDamage = 500,
maxVelocity = 8,
},
shieldraid = {
weaponDefs = {
LASER = {
range = 600,
damage = {
default = 50,
},
},
},
},
}</nowiki>
As before, we now take this text, [https://www.base64encode.org/ base64 encode] it, and copy it into Tweak Units. Encodings can be shortened by removing whitespace prior to encoding.
<pre style="display:block;overflow:auto">e2Nsb2FrcmFpZCA9IHttYXhEYW1hZ2UgPSA1MDAsbWF4VmVsb2NpdHkgPSA4LH0sc2hpZWxkcmFpZCA9IHt3ZWFwb25EZWZzID0ge0xBU0VSID0ge3JhbmdlID0gNjAwLGRhbWFnZSA9IHtkZWZhdWx0ID0gNTAsfSx9LH0sfSx9</pre>

== Mass post-processing ==

The above example deal with specific values for a single unit (e.g. "make Glaive have 500 health").
It is also possible to write Lua code that works on units, including changing values for all units or doing some sort of logic. This time, the option is not "Tweak Units" but "Tweak Defs". Again, it should be encoded to base64.

Here's an example:
<nowiki>for name, ud in pairs(UnitDefs) do
if ud.maxvelocity then
ud.maxvelocity = ud.maxvelocity*10
else
ud.maxdamage = ud.maxdamage*5
end
end</nowiki>

UnitDefs is a Lua table indexed with unit names as above (for example "cloakraid" for Glaive) whose values are the unit def tables in a similar format as for tweakunits, BUT WILL ALL KEYS LOWERCASE. This snippet increases unit speeds 10 times for all mobiles and health 5 times for all statics. Pay attention that some fields may be nil (for another example, death explosions are weapons but don't have a reload time).

Happy hacking!

[[File:Zk_1_7_11_0_cover.jpg|frame|center]]

[[Category:Development]]{{Navbox manual}}

Startbox API

2021-05-17T15:51:14Z

Sprung: Gametype API: fix code anchor

== Start boxes ==

Each team has a defined starting area in which its players can spawn their commanders - these are called start boxes. Map makers can define how these areas look like by including a config file inside their map archive.

== The config file ==

The file which you need to include is
mapconfig/map_startboxes.lua

It consists of Lua code which returns 2 tables: one with the start box layout for the current match and one that contains possible box counts.

For examples see the bottom of this page.

== Box counts ==

Let's start from the last table because it is the simplest. This is just a list of how many teams the map is designed for.

Let's take [http://zero-k.info/Maps/Detail/8162 Throne] as an example. It has an outer ring with 7 starting areas so it can be played as a 7-team FFA. There are also rings with 3 and 5 areas so 3- and 5-team FFAs are also possible setups. Finally, you could play a duel between any two positions from the same ring. (The real Throne config is a fair bit more complicated than that but you get the idea.)

Thus, the possible team counts are 2, 3, 5, and 7. Let's define a Lua table for that:
local playercounts = {2, 3, 5, 7}

This is mostly important for fancy FFA maps. Simple duel/teamgame maps will usually just have 2 as the only value here:
local playercounts = {2}

== The boxes ==

Now, the most tedious part. The boxes do not need to actually be boxes, they can be any arbitrary shape (even concave or disjoint). This is achieved by having the boxes defined as a set of polygons.

There is a widget which lets you draw the polygons ingame, it's called "Startbox Editor" and is under the "For Developers" tab in the widget list (press Alt+F11, and don't touch anything else unless you know what you're doing).

To draw a polygon, use LMB - either drag a line or click points:

[[File:Startbox API 1.jpg]]

Once you draw a full loop, press RMB to close it. Make sure the line does not cross itself. Finished polygons are a bit darker.

[[File:Startbox API 2.jpg]]

Now you can add another polygon if you want. These will all be a part of the same team.

[[File:Startbox API 3.jpg]]

If you want to delete the last created polygon, press D.
Once you are satisfied with the area, press S. Now you can draw the area for another team.

Once you create all the boxes, go to your Spring directory and find the infolog. There you will see a bunch of code like
boxes = {
stuff
},

Each of those tables is a team's startbox. The config is an array (indexed from 0) of each team's startbox data. The box data from the generator will go to a team's config entry. Like this:
local main_config = {
[0] = {
boxes = {
stuff
},
-- more entries will go there later!
},
[1] = {
boxes = {
stuff
},
},
}

The layout is a normal Lua table so you can use all the usual table manipulation methods. For example you could add more area based on how many people there are, or generate them dynamically.

=== The recommended start points ===

This sub-table defines recommended start points within each box. These are points on which CAI bots will spawn. The first point is special: human players who did not pick start position will also spawn here and so will any extra CAI if there are more of them than the spots; as such having at least one startpoint in each box is mandatory. These points are also marked on people's UI as circles.

Defining these is very simple. It's very similar to how start areas were defined. Ingame you can hold Space over a point to see its coordinates. These are written down for boxes similarly to the areas:
local main_config = {
[0] = {
boxes = {
stuff
},
startpoints = {
{123, 456}, -- X, Z
{654, 321},
-- as many as you want, it's good if there are as many as you want people per team
},
},
[1] = {
boxes = {
stuff
},
startpoints = {
{789, 789},
{987, 987},
},
},
}

Of course, the start positions should match the areas, though they don't have to.

== Putting these together ==

You can give each team a name, alongside a shorter backup if the first one is too large. Here's how:

[0] = {
boxes = { stuff },
startpoints = { stuff },
nameLong = "South-West",
nameShort = "SW",
}

It serves to identify the team so while it's good to use something that describes placement, you can get creative. For example:
* "North", "South-East"
* "5 o'clock"
* real-world style maps could have names like "Russia" or "America"
* asymmetric maps can use landmarks, for example "Lake" vs "Desert"
* for missions it's good to use storyline names, eg "Empire" vs "Dynasty"

== Summary ==

Now just return the config table and the playercounts table.
return main_config, playercounts

The exact format for the config table that should get returned is

{
[0] = { -- a single team's data. Indexed from 0
boxes = {
{ -- a polygon
{123, 456}, -- a vertex of the polygon. X, Z.
{234, 567}, -- another vertex
{345, 678},
-- more vertices
},
{ -- another polygon
-- vertices
},
-- more polygons
},
startpoints = {
{123, 456}, -- X, Z
{654, 321},
-- more points
},
nameLong = "longer string with team name",
nameShort = "short",
},
[1] = { -- another team's data
boxes = { ... },
startpoints = { ... },
nameLong = "...",
nameShort = "...",
},
-- more teams
}

== Advanced stuff ==
The config has access to Spring Lua API so it is possible to do a lot of dynamic things. In particular, you can use math.random without worry.

You can make stuff dependent on the game mode. There are functions which return the gametype, such as `Spring.Utilities.Gametype.is1v1()`. The full list is here: https://github.com/ZeroK-RTS/Zero-K/blob/master/LuaRules/Utilities/teamFunctions.lua#L74

An important thing is that #Spring.GetAllTeams() will return a wrong value due to fake technical teams and Gaia. Instead, use Spring.Utilities.GetTeamCount() to get the real number of teams.

== Examples ==

* [https://github.com/ZeroK-RTS/Zero-K/blob/master/LuaRules/Configs/StartBoxes/SpeedMetal.lua SpeedMetal] - the simplest layout, just two squares.
* [https://github.com/ZeroK-RTS/Zero-K/blob/master/LuaRules/Configs/StartBoxes/DeltaSiegeDry.lua DSD] - huge polygons, but otherwise very simple.
* [https://github.com/ZeroK-RTS/Zero-K/blob/master/LuaRules/Configs/StartBoxes/Sever%201.lua#L343 Sever] - shows an example of smaller boxes for 1v1 and larger for teams.
* [https://github.com/ZeroK-RTS/Zero-K/blob/master/LuaRules/Configs/StartBoxes/Isle%20of%20Grief%200.2.lua Isle of Grief] - shows a smart approach, one of the boxes is not defined rigidly but is a mirror of the other (only really feasible for rough boxes or perfectly symmetrical maps).
* [https://github.com/ZeroK-RTS/Zero-K/blob/master/LuaRules/Configs/StartBoxes/Aum_1.1.lua Aum] - another small trick, this time 5-way radial symmetry.
* [https://github.com/ZeroK-RTS/Zero-K/blob/master/LuaRules/Configs/StartBoxes/Throne%20v1.lua Throne] - multiple boxes defined, with a system to pick some of them based on how many teams there are.
* [https://github.com/ZeroK-RTS/Zero-K/blob/master/LuaRules/Configs/StartBoxes/Speed_Ball_10x10.lua Speedball] - shows boxes that are generated completely algorithmically.
* [https://github.com/ZeroK-RTS/Zero-K/blob/master/LuaRules/Configs/StartBoxes/Mearth_v4.lua#L6 Middle-Earth] - interesting team names.
* [https://github.com/ZeroK-RTS/Zero-K/blob/master/LuaRules/Configs/StartBoxes/Adansonia%20v2.lua Adansonia v2] - shows synchronizing boxes across map versions.
* [https://github.com/ZeroK-RTS/Zero-K/blob/master/LuaRules/Configs/StartBoxes/duck.lua Duck] - boxless config for silly maps where everybody can start anywhere.

[[Category:Development]]{{Navbox manual}}

HLT

2021-04-06T15:41:24Z

Sprung: Setup redirect: HLT -> Stinger

#REDIRECT [[Stinger]]

Award

2020-06-24T14:32:11Z

Sprung: Add CA award to the example

At the end of every battle, players are '''award'''ed with shiny trophies for various achievements during the game. Some awards are presented every game, while others are less common. It takes outstanding performance with the relevant unit set to receive an award.

There are also event-based awards which are never awarded in normal games, for example tournament cups.

All damage-related awards except Big Purple Heart use metal value to compare performance. Such awards are only given if the damage dealt with those weapons/units compares favorably to the average damage done by other players.

== The Awards ==

=== Generic Awards ===
* http://zero-k.info/img/Awards/trophy_pwn.png '''Complete Annihilation''': always awarded to the player who dealt the most damage.
* http://zero-k.info/img/Awards/trophy_ouch.png '''Big Purple Heart''': always awarded to the player who received the most health damage.

* http://zero-k.info/img/Awards/trophy_reclaim.png '''Spoils of War''': efficient usage of reclaim.
* http://zero-k.info/img/Awards/trophy_mex.png '''Mineral Prospector''': building metal extractors.
* http://zero-k.info/img/Awards/trophy_mexkill.png '''Loot & Pillage''': raiding enemy metal extractors.
* http://zero-k.info/img/Awards/trophy_shell.png '''Turtle Shell''': effective use of defense.
* http://zero-k.info/img/Awards/trophy_nux.png '''Apocalyptic Achievement Award''': employing superweapons.
* http://zero-k.info/img/Awards/trophy_air.png '''Air Force General''': exceptional play with airborne units.
* http://zero-k.info/img/Awards/trophy_navy.png '''Fleet Admiral''': successful ship usage.
* http://zero-k.info/img/Awards/trophy_slow.png '''Traffic Cop''': applying slow damage.
* http://zero-k.info/img/Awards/trophy_emp.png '''EMP Wizard''': dealing EMP damage.
* http://zero-k.info/img/Awards/trophy_kam.png '''Kamikaze Award''': heroic usage of self-destructing units.
* http://zero-k.info/img/Awards/trophy_terra.png '''Legendary Landscaper''': excessive terraforming.
* http://zero-k.info/img/Awards/trophy_comm.png '''Master and Commander''': Using your commander like a boss
* http://zero-k.info/img/Awards/trophy_fire.png '''Master Grill-Chef''': dealing fire damage.
* http://zero-k.info/img/Awards/trophy_cap.png '''Master of Puppets''': capturing enemy units.
* http://zero-k.info/img/Awards/trophy_rezz.png '''Vile Necromancer''': resurrecting wreckage.
* http://zero-k.info/img/Awards/trophy_head.png '''Head Hunter''': eliminating enemy commanders.
* http://zero-k.info/img/Awards/trophy_share.png '''Share Bear''': sharing units to allies.
* http://zero-k.info/img/Awards/trophy_vet.png '''Decorated Veteran''': extremely efficient usage of a single unit.

=== Chicken Awards ===
* http://zero-k.info/img/Awards/trophy_heart.png '''Heart Breaker''': killing the Chicken Queen.
* http://zero-k.info/img/Awards/trophy_sweeper.png '''Land Sweeper''': destroying Chicken Roosts.
* http://zero-k.info/img/Awards/trophy_dragon.png '''Dragon Slayer''': eliminating Chicken Dragons.

=== Event Awards ===
* http://zero-k.info/img/Awards/trophy_gold.png http://zero-k.info/img/Awards/trophy_silver.png http://zero-k.info/img/Awards/trophy_bronze.png '''Tournament Cups''': awarded for the winners of the monthly tournaments.
* http://zero-k.info/img/Awards/coingold.png http://zero-k.info/img/Awards/coinsilver.png http://zero-k.info/img/Awards/coinbronze.png '''Coins''': awarded for minor community events.

= Technical details =

Some awards have flat requirements for being awarded:
* Mineral Prospector / Loot & Pillage take a minimum of 15 mexes built/killed to earn.
* Legendary Landscaper takes a minimum of 1000m worth of terraform.
* Head Hunter / Dragon Slayer / Land Sweeper require 3/3/20 commander/dragon/nest kills.
* Master of Puppets / Vile Necromancer / Share Bear require 1000/3000/5000m worth of units captured/resurrected/shared respectively.
* Decorated Veteran requires the unit to make 300% cost, with a minimum of 1000m.
* Queen Heartbreaker requires the chicken queen to die.

Big Purple Heart operates on health and considers environmental damage (such as collisions, forest fires, or lava). All other damage awards operate on cost and only consider PvP damage.

Using a damage type is not enough to be eligible for the appropriate award. Each award has a dynamic threshold that scales with the general game size. Eligibility is decided thus:
* Take the average physical damage done by all other players except yourself.
* Multiply by a per-award factor given in the table below.
* Compare your own damage with the given type. You are eligible if your damage is higher.

{| class="wikitable"
|+ Difficulty factors
|-
! Award
! Multiplier
|-
| EMP Wizard
| 1.2
|-
| Fleet Admiral Airforce General Traffic Cop
| 1
|-
| Turtle Shell Master Grill Chef
| 0.5
|-
| Apocalyptic Achievement Award Kamikaze Award Master and Commander
| 0.3
|-
| Spoils of War
| 0.06
|}

== Example ==

A did 900m of damage, composed of 450m of fire damage, 350m of kamikaze damage and 100m general damage.
B did 800m kamikaze damage.
C did 1200m general damage.

For A, the average of others' damage is (800 + 1200) / 2 == 1000.
For B, the average is (900 + 1200) / 2 == 1050.
For C, the average is (900 + 800) / 2 == 850.

The multiplier for kamikaze is 0.3 and for fire is 0.5, so:
A would have to do 1000 * 0.5 == 500 fire damage to be eligible. He did 450 so he won't get it.
A would have to do 1000 * 0.3 == 300 kamikaze damage. He did 350 so he is eligible.
B would have to do 1050 * 0.3 == 317 kamikaze damage. He did 800 so is also eligible.

B did 800 kamikaze damage and A did 350 so B gets the kamikaze award.
Nobody is eligible for the fire award.
C did the most total damage so gets the Complete Annihilation award.
{{Navbox manual}}

Template:Navbox units

2020-06-24T11:17:42Z

Sprung: Surfboard is no more

{{Navbox
| name = Navbox units
| title = [[Units]]
| state = uncollapsed
| listclass = hlist

| group1 = [[Cloakbot Factory|Cloakbots]]
| list1 = * [[Conjurer]]
* [[Glaive]]
* [[Scythe]]
* [[Ronin]]
* [[Reaver]]
* [[Knight]]
* [[Sling]]
* [[Phantom]]
* [[Gremlin]]
* [[Imp]]
* [[Iris]]

| group2 = [[Shieldbot Factory|Shieldbots]]
| list2 = * [[Convict]]
* [[Dirtbag]]
* [[Bandit]]
* [[Rogue]]
* [[Thug]]
* [[Outlaw]]
* [[Felon]]
* [[Racketeer]]
* [[Vandal]]
* [[Snitch]]
* [[Aspis]]

| group3 = [[Rover Assembly|Rovers]]
| list3 = * [[Mason]]
* [[Dart]]
* [[Scorcher]]
* [[Fencer]]
* [[Ripper]]
* [[Ravager]]
* [[Dominatrix]]
* [[Badger]]
* [[Impaler]]
* [[Crasher]]

| group4 = [[Hovercraft Platform|Hovercraft]]
| list4 = * [[Quill]]
* [[Dagger]]
* [[Scalpel]]
* [[Halberd]]
* [[Claymore]]
* [[Mace]]
* [[Lance]]
* [[Flail]]
* [[Bolas]]

| group5 = [[Gunship Plant|Gunships]]
| list5 = * [[Wasp]]
* [[Blastwing]]
* [[Gnat]]
* [[Locust]]
* [[Harpy]]
* [[Nimbus]]
* [[Revenant]]
* [[Krow]]
* [[Trident]]
* [[Charon]]
* [[Hercules]]

| group6 = [[Airplane Plant|Airplanes]]
| list6 = * [[Crane]]
* [[Swift]]
* [[Raptor]]
* [[Raven]]
* [[Phoenix]]
* [[Thunderbird]]
* [[Likho]]
* [[Sparrow]]
* [[Owl]]

| group7 = [[Spider Factory|Spiders]]
| list7 = * [[Weaver]]
* [[Flea]]
* [[Hermit]]
* [[Venom]]
* [[Redback]]
* [[Recluse]]
* [[Crab]]
* [[Tarantula]]
* [[Widow]]

| group8 = [[Jumpbot Factory|Jumpbots]]
| list8 = * [[Constable]]
* [[Puppy]]
* [[Pyro]]
* [[Placeholder]]
* [[Moderator]]
* [[Jack]]
* [[Jugglenaut]]
* [[Firewalker]]
* [[Toad]]
* [[Skuttle]]

| group9 = [[Tank Foundry|Heavy Tanks]]
| list9 = * [[Welder]]
* [[Kodachi]]
* [[Blitz]]
* [[Ogre]]
* [[Minotaur]]
* [[Cyclops]]
* [[Emissary]]
* [[Tremor]]
* [[Ettin]]

| group10 = [[Amphbot Factory|Amphbots]]
| list10 = * [[Conch]]
* [[Duck]]
* [[Archer]]
* [[Buoy]]
* [[Scallop]]
* [[Grizzly]]
* [[Angler]]
* [[Limpet]]
* [[Lobster]]
* [[Djinn]]

| group11 = [[Shipyard|Ships]]
| list11 = * [[Mariner]]
* [[Cutter]]
* [[Hunter]]
* [[Seawolf]]
* [[Corsair]]
* [[Mistral]]
* [[Siren]]
* [[Envoy]]
* [[Zephyr]]

| group12 = [[Strider Hub|Striders]]
| list12 = * [[Athena]]
* [[Ultimatum]]
* [[Scorpion]]
* [[Dante]]
* [[Merlin]]
* [[Funnelweb]]
* [[Paladin]]
* [[Detriment]]
* [[Shogun]]
* [[Reef]]
* [[Scylla]]

| group13 = [[Missile Silo|Tactical Missiles]]
| list13 = * [[Eos]]
* [[Quake]]
* [[Shockley]]
* [[Inferno]]

| group14 = Other Units
| list14 = * [[Commander]]
* [[Firefly]]
* [[Viper]]
* [[Gull]]
* [[Glint]]

| group15 = [[Chicken Defense|Chickens]]
| list15 = * [[Chicken]]
* [[Pigeon]]
* [[Spiker]]
* [[Cockatrice]]
* [[Lobber]]
* [[Wurm]]
* [[Roc]]
* [[Sporeshooter]]
* [[Leaper]]
* [[Talon]]
* [[Basilisk]]
* [[Blobber]]
* [[Blimpy]]
* [[Tiamat]]
* [[White Dragon]]
* [[Chicken Queen]] ([[Chicken Flyer Queen|flying]])
* [[Digger]]
* [[Dodo]]
* [[Spidermonkey]]
* [[Blooper]]

| group16 = Unused Units
| list16 = * [[Nebula]]
* [[Spicula]]
* [[Kestrel]]
* [[Eclipse]]
* [[Trisula]]
* [[Morningstar]]
* [[Lancelet]]
* [[Daimyo]]
* [[Vanquisher]]
* [[Listener (burrowed)]]
* [[Chicken Queen (old)]]
* [[Chicken Brood Queen]]

| below = [[Buildings]]

}}

<includeonly>
[[Category:Units]]
</includeonly>

Internal unit names

2020-06-24T11:08:31Z

Sprung: Surfboard is gone

This page lists the '''internal unit names''' of [[units]] and[[ buildings]] in Zero-K, including test/unused/template units and excluding commanders.

== Unit names and IDs ==
:''Click a header to sort the table''
{|class="wikitable sortable"
! Unit def name || Human name
|-
|amphaa || [[Angler]]
|-
|amphassault || [[Grizzly]]
|-
|amphbomb || [[Limpet]]
|-
|amphcon || [[Conch]]
|-
|amphfloater || [[Buoy]]
|-
|amphimpulse || [[Archer]]
|-
|amphlaunch || [[Lobster]]
|-
|amphraid || [[Duck]]
|-
|amphriot || [[Scallop]]
|-
|amphtele || [[Djinn]]
|-
|assaultcruiser || [[Vanquisher]]
|-
|asteroid || [[Asteroid]]
|-
|athena || [[Athena]]
|-
|bomberassault || [[Eclipse]]
|-
|bomberdisarm || [[Thunderbird]]
|-
|bomberheavy || [[Likho]]
|-
|bomberprec || [[Raven]]
|-
|bomberriot || [[Phoenix]]
|-
|bomberstrike || [[Kestrel]]
|-
|chicken || [[Chicken]]
|-
|chicken_blimpy || [[Blimpy]]
|-
|chicken_digger || [[Digger]]
|-
|chicken_digger_b || [[Digger (burrowed)]]
|-
|chicken_dodo || [[Dodo]]
|-
|chicken_dragon || [[White Dragon]]
|-
|chicken_drone || [[Drone]]
|-
|chicken_drone_starter || [[Drone]]
|-
|chicken_leaper || [[Leaper]]
|-
|chicken_listener || [[Listener]]
|-
|chicken_listener_b || [[Listener (burrowed)]]
|-
|chicken_pigeon || [[Pigeon]]
|-
|chicken_rafflesia || [[Rafflesia]]
|-
|chicken_roc || [[Roc]]
|-
|chicken_shield || [[Blooper]]
|-
|chicken_spidermonkey || [[Spidermonkey]]
|-
|chicken_sporeshooter || [[Sporeshooter]]
|-
|chicken_tiamat || [[Tiamat]]
|-
|chickena || [[Cockatrice]]
|-
|chickenblobber || [[Blobber]]
|-
|chickenbroodqueen || [[Chicken Brood Queen]]
|-
|chickenc || [[Basilisk]]
|-
|chickend || [[Chicken Tube]]
|-
|chickenf || [[Talon]]
|-
|chickenflyerqueen || [[Chicken Flyer Queen]]
|-
|chickenlandqueen || [[Chicken Queen]]
|-
|chickenr || [[Lobber]]
|-
|chickens || [[Spiker]]
|-
|chickenspire || [[Chicken Spire]]
|-
|chickenwurm || [[Wurm]]
|-
|cloakaa || [[Gremlin]]
|-
|cloakarty || [[Sling]]
|-
|cloakassault || [[Knight]]
|-
|cloakbomb || [[Imp]]
|-
|cloakcon || [[Conjurer]]
|-
|cloakheavyraid || [[Scythe]]
|-
|cloakjammer || [[Iris]]
|-
|cloakraid || [[Glaive]]
|-
|cloakriot || [[Reaver]]
|-
|cloakskirm || [[Ronin]]
|-
|cloaksnipe || [[Phantom]]
|-
|damagesink || [[Damage Sink thing]]
|-
|dronecarry || [[Gull]]
|-
|dronefighter || [[Spicula]]
|-
|droneheavyslow || [[Viper]]
|-
|dronelight || [[Firefly]]
|-
|empiricaldpser || [[Empirical DPS thing]]
|-
|empiricaldpsersmall || [[Empirical DPS thing (small)]]
|-
|empmissile || [[Shockley]]
|-
|energyfusion || [[Fusion Reactor]]
|-
|energygeo || [[Geothermal Generator]]
|-
|energyheavygeo || [[Advanced Geothermal]]
|-
|energypylon || [[Energy Pylon]]
|-
|energysingu || [[Singularity Reactor]]
|-
|energysolar || [[Solar Collector]]
|-
|energywind || [[Wind/Tidal Generator]]
|-
|factoryamph || [[Amphbot Factory]]
|-
|factorycloak || [[Cloakbot Factory]]
|-
|factorygunship || [[Gunship Plant]]
|-
|factoryhover || [[Hovercraft Platform]]
|-
|factoryjump || [[Jumpbot Factory]]
|-
|factoryplane || [[Airplane Plant]]
|-
|factoryshield || [[Shieldbot Factory]]
|-
|factoryship || [[Shipyard]]
|-
|factoryspider || [[Spider Factory]]
|-
|factorytank || [[Tank Foundry]]
|-
|factoryveh || [[Rover Assembly]]
|-
|fakeunit || [[Fake radar signal]]
|-
|fakeunit_aatarget || [[Fake AA target]]
|-
|fakeunit_los || [[LOS Provider]]
|-
|generic_tech || [[Generic Neutral Structure]]
|-
|grebe || [[Grebe]]
|-
|gunshipaa || [[Trident]]
|-
|gunshipassault || [[Revenant]]
|-
|gunshipbomb || [[Blastwing]]
|-
|gunshipcon || [[Wasp]]
|-
|gunshipemp || [[Gnat]]
|-
|gunshipheavyskirm || [[Nimbus]]
|-
|gunshipheavytrans || [[Hercules]]
|-
|gunshipkrow || [[Krow]]
|-
|gunshipraid || [[Locust]]
|-
|gunshipskirm || [[Harpy]]
|-
|gunshiptrans || [[Charon]]
|-
|hoveraa || [[Flail]]
|-
|hoverarty || [[Lance]]
|-
|hoverassault || [[Halberd]]
|-
|hovercon || [[Quill]]
|-
|hoverdepthcharge || [[Claymore]]
|-
|hoverminer || [[Dampener]]
|-
|hoverraid || [[Dagger]]
|-
|hoverriot || [[Mace]]
|-
|hovershotgun || [[Punisher]]
|-
|hoverskirm || [[Scalpel]]
|-
|hoverskirm2 || [[Trisula]]
|-
|hoversonic || [[Morningstar]]
|-
|jumpaa || [[Toad]]
|-
|jumparty || [[Firewalker]]
|-
|jumpassault || [[Jack]]
|-
|jumpblackhole || [[Placeholder]]
|-
|jumpbomb || [[Skuttle]]
|-
|jumpcon || [[Constable]]
|-
|jumpraid || [[Pyro]]
|-
|jumpscout || [[Puppy]]
|-
|jumpskirm || [[Moderator]]
|-
|jumpsumo || [[Jugglenaut]]
|-
|mahlazer || [[Starlight]]
|-
|napalmmissile || [[Inferno]]
|-
|nebula || [[Nebula]]
|-
|planecon || [[Crane]]
|-
|planefighter || [[Swift]]
|-
|planeheavyfighter || [[Raptor]]
|-
|planescout || [[Owl]]
|-
|pw_artefact || [[Ancient Artefact]]
|-
|pw_bomberfac || [[Bomber Factory]]
|-
|pw_dropfac || [[Dropship Factory]]
|-
|pw_estorage || [[Energy Storage]]
|-
|pw_estorage2 || [[Double Energy Storage]]
|-
|pw_garrison || [[Field Garrison]]
|-
|pw_gaspowerstation || [[Gas Power Station]]
|-
|pw_generic || [[Generic Neutral Structure]]
|-
|pw_grid || [[Planetary Defense Grid]]
|-
|pw_guerilla || [[Guerilla Jumpgate]]
|-
|pw_hq_attacker || [[Attacker Command]]
|-
|pw_hq_defender || [[Defender Command]]
|-
|pw_inhibitor || [[Wormhole Inhibitor]]
|-
|pw_interception || [[Interception Network]]
|-
|pw_metal || [[Ancient Fabricator]]
|-
|pw_mine || [[Power Generator Unit]]
|-
|pw_mine2 || [[Orbital Solar Array]]
|-
|pw_mine3 || [[Planetary Geothermal Tap]]
|-
|pw_mstorage2 || [[Metal Storage]]
|-
|pw_relay || [[Communication Relay]]
|-
|pw_techlab || [[Tech Lab]]
|-
|pw_warpgate || [[Warp Gate]]
|-
|pw_warpgatealt || [[Warp Gate]]
|-
|pw_warpjammer || [[Warp Jammer]]
|-
|pw_wormhole || [[Wormhole Generator]]
|-
|pw_wormhole2 || [[Improved Wormhole]]
|-
|raveparty || [[Disco Rave Party]]
|-
|rocksink || [[Rocking Damage Sink thing]]
|-
|roost || [[Roost]]
|-
|seismic || [[Quake]]
|-
|shieldaa || [[Vandal]]
|-
|shieldarty || [[Racketeer]]
|-
|shieldassault || [[Thug]]
|-
|shieldbomb || [[Snitch]]
|-
|shieldcon || [[Convict]]
|-
|shieldfelon || [[Felon]]
|-
|shieldraid || [[Bandit]]
|-
|shieldriot || [[Outlaw]]
|-
|shieldscout || [[Dirtbag]]
|-
|shieldshield || [[Aspis]]
|-
|shieldskirm || [[Rogue]]
|-
|shipaa || [[Zephyr]]
|-
|shiparty || [[Envoy]]
|-
|shipassault || [[Siren]]
|-
|shipcarrier || [[Reef]]
|-
|shipcon || [[Mariner]]
|-
|shipheavyarty || [[Shogun]]
|-
|shipriot || [[Corsair]]
|-
|shipscout || [[Cutter]]
|-
|shipskirm || [[Mistral]]
|-
|shiptorpraider || [[Hunter]]
|-
|spideraa || [[Tarantula]]
|-
|spideranarchid || [[Anarchid]]
|-
|spiderantiheavy || [[Widow]]
|-
|spiderassault || [[Hermit]]
|-
|spidercon || [[Weaver]]
|-
|spidercrabe || [[Crab]]
|-
|spideremp || [[Venom]]
|-
|spiderriot || [[Redback]]
|-
|spiderscout || [[Flea]]
|-
|spiderskirm || [[Recluse]]
|-
|starlight_satellite || [[Glint]]
|-
|staticantinuke || [[Antinuke]]
|-
|staticarty || [[Cerberus]]
|-
|staticcon || [[Caretaker]]
|-
|staticheavyarty || [[Big Bertha]]
|-
|staticheavyradar || [[Advanced Radar]]
|-
|staticjammer || [[Cornea]]
|-
|staticmex || [[Metal Extractor]]
|-
|staticmissilesilo || [[Missile Silo]]
|-
|staticnuke || [[Trinity]]
|-
|staticradar || [[Radar Tower]]
|-
|staticrearm || [[Airpad]]
|-
|staticshield || [[Aegis]]
|-
|staticsonar || [[Sonar Station]]
|-
|staticstorage || [[Storage]]
|-
|striderantiheavy || [[Ultimatum]]
|-
|striderarty || [[Merlin]]
|-
|striderbantha || [[Paladin]]
|-
|striderdante || [[Dante]]
|-
|striderdetriment || [[Detriment]]
|-
|striderfunnelweb || [[Funnelweb]]
|-
|striderhub || [[Strider Hub]]
|-
|striderscorpion || [[Scorpion]]
|-
|subraider || [[Seawolf]]
|-
|subscout || [[Lancelet]]
|-
|subtacmissile || [[Scylla]]
|-
|tacnuke || [[Eos]]
|-
|tankaa || [[Ettin]]
|-
|tankarty || [[Emissary]]
|-
|tankassault || [[Minotaur]]
|-
|tankcon || [[Welder]]
|-
|tankheavyarty || [[Tremor]]
|-
|tankheavyassault || [[Cyclops]]
|-
|tankheavyraid || [[Blitz]]
|-
|tankraid || [[Kodachi]]
|-
|tankriot || [[Ogre]]
|-
|tele_beacon || [[Lamp]]
|-
|terraunit || [[Terraform]]
|-
|tiptest || [[Turn In Place test]]
|-
|turretaaclose || [[Hacksaw]]
|-
|turretaafar || [[Chainsaw]]
|-
|turretaaflak || [[Thresher]]
|-
|turretaaheavy || [[Artemis]]
|-
|turretaalaser || [[Razor]]
|-
|turretantiheavy || [[Lucifer]]
|-
|turretemp || [[Faraday]]
|-
|turretgauss || [[Gauss]]
|-
|turretheavy || [[Desolator]]
|-
|turretheavylaser || [[Stinger]]
|-
|turretimpulse || [[Newton]]
|-
|turretlaser || [[Lotus]]
|-
|turretmissile || [[Picket]]
|-
|turretriot || [[Stardust]]
|-
|turretsunlance || [[Sunlance]]
|-
|turrettorp || [[Urchin]]
|-
|vehaa || [[Crasher]]
|-
|veharty || [[Badger]]
|-
|vehassault || [[Ravager]]
|-
|vehcapture || [[Dominatrix]]
|-
|vehcon || [[Mason]]
|-
|vehheavyarty || [[Impaler]]
|-
|vehraid || [[Scorcher]]
|-
|vehriot || [[Ripper]]
|-
|vehscout || [[Dart]]
|-
|vehsupport || [[Fencer]]
|-
|wolverine_mine || [[Claw]]
|-
|zenith || [[Zenith]]
|}

== Generation code ==
The above wiki table can be generated using a widget with the following Lua code:
<pre>
function widget:Initialize()
local file = io.open("testwidget.txt", "w")
file:write([[{|class="wikitable sortable"]] .. "\n")
file:write("! Unit def name || Human name\n") -- || Description\n")
for i=1,#UnitDefs do
local ud = UnitDefs[i]
if not ud.customParams.level then
local unitname = ud.name
local name = ud.humanName
local desc = Spring.Utilities.GetDescription(ud, nil)
local helptext = Spring.Utilities.GetHelptext(ud)
file:write("|-\n")
file:write("|" .. unitname .. " || " .. "[[" .. name .. "]]\n") -- .. " || " .. desc .. "\n") -- .. "\t" .. helptext .. "\n")
end
end
file:write("|}")
file:flush()
file:close()
end
</pre>

[[Category:Development]]

User:Aquanim/DraftMapMakingGuide

2020-06-15T09:15:48Z

Sprung: Add a link to startbox API help page

= Minimal Brief Guide =

For more detail on each of these steps read the later sections of the document (TODO: when these are actually written lol)

This guide assumes that you are using a version of Zero-K installed through Steam. You can still make maps if you installed by some other method but you may need to modify some of the later steps.

== Download Tools ==

* 7zip - https://www.7-zip.org/download.html
* pymapconv - clone or download https://github.com/Beherith/springrts_smf_compiler somewhere, then copy pymapconv.exe and nvdxt.exe to a new directory to keep things simple
* map blueprint - clone or download https://github.com/Aquanim/ZKMapBlueprint

== Create Images ==

For a 10x10 (TitanDuel-size) map, create the following images with a tool of your choice:

* A height map grayscale image with dimensions 641 x 641, saved as an 8-bit .bmp or a 16-bit .png. (The latter is preferred but not all tools offer 16-bit output.) The brighter a pixel is the higher the corresponding part of the map will be.
* A texture map colour image with dimensions 5120 x 5120, saved as a .bmp

For a different size map, multiply the height/width of the map by 64 and add 1 to get the right size for the heightmap; multiply the height/width of the map by 512 to get the right size for the texture map.

Put these images in the same directory as pymapconv.exe from the previous step (may not strictly be required but keeps things simple). 

TODO: SME and Springboard tools

== Compile Your Map ==
Run pymapconv.exe and fill in the following fields...
* An output file name - ideally this should be the name of your map, possibly with a version number. File extension .smf, will also generate a .smt. '''IMPORTANT:''' Do not rename these files after compiling!
* Use the buttons to select the texture and heightmap images you made in the previous step.
* I expect the minimum/maximum height values to be overridden by mapinfo.lua later but you might as well set them.
* Scroll down to the NVDXT option and make sure it says "-Sinc -quality_highest". Also probably a good idea to tick the CLEAN option.
* Untick everything else, press "Save options as" if you like, then press the "Compile" button. 

== Construct .sdd File ==
* Rename ZKMapBlueprint_v0.0.sdd to have the name of your map. A version identifier is advisable as well. Keep the .sdd extension.
* Copy the .smf and .smt files produced by pymapconv.exe into the /maps subfolder of the .sdd folder. (There should be mapblueprint.smf and mapblueprint.smt files here, you can delete them.)
* In the root of the .sdd folder there should be a file "mapinfo.lua". Open this with a text editor. This file contains a bunch of stuff but there are only a few items we are interested in for now:
** Near the start of the file change the ''author'', ''description'', ''name'', ''shortname'' and ''version'' variables to suit you and your map.
** Scroll down a bit to the "smf" section and change the ''maxheight'' and ''minheight'' numbers to suit your map. Also change the file name after ''smtFileName0'' so that it has your .smt file's name.
* To test your map, copy the .sdd directory into the /maps folder of your Zero-K install. In the settings make sure that "Only featured maps" is disabled. Then open a Skirmish game, click on the current map, select your map from the list, and play. (You might want to make the enemy AI inactive. The minimap in the lobby will be blank, don't worry about this for now.)
* If you want to change your map you will need to replace the files in your ZK maps folder, then restart ZK, in order to load the new version.

== Metal and Startboxes ==
Now that you can look at your height and texturemap ingame this is a good time to sort out your metal spots and start locations.
=== Metal spots ===
In the /mapconfig subfolder of the .sdd file there is a "map_metal_layout.lua" file. The blueprint contains two metal spots as an example; replace them with your own.

=== Startboxes ===
In the /mapconfig subfolder of the .sdd file there is a "map_startboxes.lua" file. This specifies each team's startboxes as well as default start locations.

Some hints for configuring the metal and startbox files:

* Startboxes are specified by their corner points reading clockwise around the polygon. More than one separate box for a given team is possible.
* Holding SPACE ingame will display a dialog box which (among other things) gives the X and Z coordinates of wherever your cursor is.
* The metal and startbox files are just LUA scripts. This means you don't have to write simple numbers to specify locations; you can perform arithmetic to make sure your map setup is symmetric (the startbox of the South-East team in the blueprint is an example). More advanced scripting is also possible, for example to make your startbox configuration dependent on the number of players or allyteams. See the [[http://zero-k.info/mediawiki/index.php?title=Startbox_API#Advanced_stuff Startbox API page]] .

=== Useful Tools ===

[[https://zero-k.info/mediawiki/index.php?title=User:Aquanim/DraftMapMakingGuide#Startbox_Editor_Widget Startbox Editor Widget]]

== Optional Extras ==
TODO: fill these in

You can skip this for now, but refer to the sections linked below if you want...
* Features (geovents, trees, rocks, etc)
* DNTS (fancy map details and specular map)
* Fancy mapinfo stuff (lighting, water effects, etc)
* Skybox (???)
* Other nonsense (particle effects, sound, etc)

== Upload ==

Compress the contents of the .sdd file into a 7zip, then change the file extension to “.sd7”. If you remove the .sdd from your game maps directory and put the .sd7 in its place, the map should still work.

'''IMPORTANT:''' Make sure that when you open the archive you see mapinfo.lua and not your .sdd folder! If you get this wrong the map will not work correctly.

'''IMPORTANT:''' When you compress to 7zip make sure the compression is “non-solid”.

* Make a Springfiles account at https://springfiles.com/
* Pray to your deity of choice that whoever approves Springfiles accounts checks in this month

Alternatively, get somebody else who already has an account to upload the map for you. Your name will still be listed as the author and you should still be able to upload any later updates yourself.

* Upload your map
* Pray to your deity of choice that Springfiles is actually working this week
* If your map is not listed at https://api.springfiles.com/ within 24 hours ask for help in the #zkmap channel
* Eventually see your map on the ZK website - it will be unsupported by default so make sure you set your search filter accordingly
* Test your map on the live server so there is a publically accessible replay or two - games against AIs are fine
* Ask a moderator to support/feature your map

= Tools and Resources =

== Springboard ==

== SpringMapEdit ==

== Nobiax Texture Pack ==

== Startbox Editor Widget ==
Load your map in ZK, press Alt-F11 to access the widget list, press "Search" and enter "Startbox". Enable the Startbox Editor. The ingame description doesn't say much so let's consult the [https://github.com/ZeroK-RTS/Zero-K/blob/90d61099e3fb8509645cf16d3fa2982150c81bdd/LuaUI/Widgets/dbg_startbox_editor.lua widget source file]:

[[Image:Startboxeditor1.png]]

...well, that's not a good sign. Scroll down a bit further:

[[Image:Startboxeditor2.png]]

That's more like it. Follow those instructions to create your startboxes, then open your infolog.lua (in the main zero-k directory) after you exit to retrieve the startbox information for copying into map_startboxes.lua. It's probably a good idea to turn the widget off after you are done with it.

== Upspring ==

Startbox API

2020-06-15T09:10:39Z

Sprung: Add a note about gametype functions

== Start boxes ==

Each team has a defined starting area in which its players can spawn their commanders - these are called start boxes. Map makers can define how these areas look like by including a config file inside their map archive.

== The config file ==

The file which you need to include is
mapconfig/map_startboxes.lua

It consists of Lua code which returns 2 tables: one with the start box layout for the current match and one that contains possible box counts.

For examples see the bottom of this page.

== Box counts ==

Let's start from the last table because it is the simplest. This is just a list of how many teams the map is designed for.

Let's take [http://zero-k.info/Maps/Detail/8162 Throne] as an example. It has an outer ring with 7 starting areas so it can be played as a 7-team FFA. There are also rings with 3 and 5 areas so 3- and 5-team FFAs are also possible setups. Finally, you could play a duel between any two positions from the same ring. (The real Throne config is a fair bit more complicated than that but you get the idea.)

Thus, the possible team counts are 2, 3, 5, and 7. Let's define a Lua table for that:
local playercounts = {2, 3, 5, 7}

This is mostly important for fancy FFA maps. Simple duel/teamgame maps will usually just have 2 as the only value here:
local playercounts = {2}

== The boxes ==

Now, the most tedious part. The boxes do not need to actually be boxes, they can be any arbitrary shape (even concave or disjoint). This is achieved by having the boxes defined as a set of polygons.

There is a widget which lets you draw the polygons ingame, it's called "Startbox Editor" and is under the "For Developers" tab in the widget list (press Alt+F11, and don't touch anything else unless you know what you're doing).

To draw a polygon, use LMB - either drag a line or click points:

[[File:Startbox API 1.jpg]]

Once you draw a full loop, press RMB to close it. Make sure the line does not cross itself. Finished polygons are a bit darker.

[[File:Startbox API 2.jpg]]

Now you can add another polygon if you want. These will all be a part of the same team.

[[File:Startbox API 3.jpg]]

If you want to delete the last created polygon, press D.
Once you are satisfied with the area, press S. Now you can draw the area for another team.

Once you create all the boxes, go to your Spring directory and find the infolog. There you will see a bunch of code like
boxes = {
stuff
},

Each of those tables is a team's startbox. The config is an array (indexed from 0) of each team's startbox data. The box data from the generator will go to a team's config entry. Like this:
local main_config = {
[0] = {
boxes = {
stuff
},
-- more entries will go there later!
},
[1] = {
boxes = {
stuff
},
},
}

The layout is a normal Lua table so you can use all the usual table manipulation methods. For example you could add more area based on how many people there are, or generate them dynamically.

=== The recommended start points ===

This sub-table defines recommended start points within each box. These are points on which CAI bots will spawn. The first point is special: human players who did not pick start position will also spawn here and so will any extra CAI if there are more of them than the spots; as such having at least one startpoint in each box is mandatory. These points are also marked on people's UI as circles.

Defining these is very simple. It's very similar to how start areas were defined. Ingame you can hold Space over a point to see its coordinates. These are written down for boxes similarly to the areas:
local main_config = {
[0] = {
boxes = {
stuff
},
startpoints = {
{123, 456}, -- X, Z
{654, 321},
-- as many as you want, it's good if there are as many as you want people per team
},
},
[1] = {
boxes = {
stuff
},
startpoints = {
{789, 789},
{987, 987},
},
},
}

Of course, the start positions should match the areas, though they don't have to.

== Putting these together ==

You can give each team a name, alongside a shorter backup if the first one is too large. Here's how:

[0] = {
boxes = { stuff },
startpoints = { stuff },
nameLong = "South-West",
nameShort = "SW",
}

It serves to identify the team so while it's good to use something that describes placement, you can get creative. For example:
* "North", "South-East"
* "5 o'clock"
* real-world style maps could have names like "Russia" or "America"
* asymmetric maps can use landmarks, for example "Lake" vs "Desert"
* for missions it's good to use storyline names, eg "Empire" vs "Dynasty"

== Summary ==

Now just return the config table and the playercounts table.
return main_config, playercounts

The exact format for the config table that should get returned is

{
[0] = { -- a single team's data. Indexed from 0
boxes = {
{ -- a polygon
{123, 456}, -- a vertex of the polygon. X, Z.
{234, 567}, -- another vertex
{345, 678},
-- more vertices
},
{ -- another polygon
-- vertices
},
-- more polygons
},
startpoints = {
{123, 456}, -- X, Z
{654, 321},
-- more points
},
nameLong = "longer string with team name",
nameShort = "short",
},
[1] = { -- another team's data
boxes = { ... },
startpoints = { ... },
nameLong = "...",
nameShort = "...",
},
-- more teams
}

== Advanced stuff ==
The config has access to Spring Lua API so it is possible to do a lot of dynamic things. In particular, you can use math.random without worry.

You can make stuff dependent on the game mode. There are functions which return the gametype, such as `Spring.Utilities.Gametype.is1v1()`. The full list is here: https://github.com/ZeroK-RTS/Zero-K/blob/master/LuaRules/Utilities/teamFunctions.lua#L67

An important thing is that #Spring.GetAllTeams() will return a wrong value due to fake technical teams and Gaia. Instead, use Spring.Utilities.GetTeamCount() to get the real number of teams.

== Examples ==

* [https://github.com/ZeroK-RTS/Zero-K/blob/master/LuaRules/Configs/StartBoxes/SpeedMetal.lua SpeedMetal] - the simplest layout, just two squares.
* [https://github.com/ZeroK-RTS/Zero-K/blob/master/LuaRules/Configs/StartBoxes/DeltaSiegeDry.lua DSD] - huge polygons, but otherwise very simple.
* [https://github.com/ZeroK-RTS/Zero-K/blob/master/LuaRules/Configs/StartBoxes/Sever%201.lua#L343 Sever] - shows an example of smaller boxes for 1v1 and larger for teams.
* [https://github.com/ZeroK-RTS/Zero-K/blob/master/LuaRules/Configs/StartBoxes/Isle%20of%20Grief%200.2.lua Isle of Grief] - shows a smart approach, one of the boxes is not defined rigidly but is a mirror of the other (only really feasible for rough boxes or perfectly symmetrical maps).
* [https://github.com/ZeroK-RTS/Zero-K/blob/master/LuaRules/Configs/StartBoxes/Aum_1.1.lua Aum] - another small trick, this time 5-way radial symmetry.
* [https://github.com/ZeroK-RTS/Zero-K/blob/master/LuaRules/Configs/StartBoxes/Throne%20v1.lua Throne] - multiple boxes defined, with a system to pick some of them based on how many teams there are.
* [https://github.com/ZeroK-RTS/Zero-K/blob/master/LuaRules/Configs/StartBoxes/Speed_Ball_10x10.lua Speedball] - shows boxes that are generated completely algorithmically.
* [https://github.com/ZeroK-RTS/Zero-K/blob/master/LuaRules/Configs/StartBoxes/Mearth_v4.lua#L6 Middle-Earth] - interesting team names.
* [https://github.com/ZeroK-RTS/Zero-K/blob/master/LuaRules/Configs/StartBoxes/Adansonia%20v2.lua Adansonia v2] - shows synchronizing boxes across map versions.
* [https://github.com/ZeroK-RTS/Zero-K/blob/master/LuaRules/Configs/StartBoxes/duck.lua Duck] - boxless config for silly maps where everybody can start anywhere.

[[Category:Development]]{{Navbox manual}}