Startbox API - Revision history

GoogleFrog at 00:12, 19 October 2025

2025-10-19T00:12:06Z

RandomX: /* Box counts */ Added the minimap so the reader doesn't have to click to look at it.

2022-09-03T19:47:53Z

Box counts: Added the minimap so the reader doesn't have to click to look at it.

RandomX: Calling "- For Developers -" a section rather than a tab.

2022-08-18T05:32:45Z

Calling "- For Developers -" a section rather than a tab.

RandomX: Minor highlighting and wording changes.

2022-08-18T05:12:08Z

Minor highlighting and wording changes.

RandomX: A little prettification.

2022-08-18T04:43:33Z

A little prettification.

RandomX: Enable syntax highlighter for a line of code.

2022-08-18T04:03:08Z

Enable syntax highlighter for a line of code.

Sprung: Formatting.

2022-07-31T02:00:52Z

Formatting.

Sprung: Indexing is now from 1

2022-07-31T02:00:10Z

Indexing is now from 1

Sprung: Gametype API: fix code anchor

2021-05-17T15:51:14Z

Gametype API: fix code anchor

Sprung: Add a note about gametype functions

2020-06-15T09:10:39Z

Add a note about gametype functions

@@ Line 24: / Line 24: @@
 This is mostly important for fancy FFA maps. Simple duel/teamgame maps will usually just have 2 as the only value here:
 <syntaxhighlight lang="lua">local playercounts = {2}</syntaxhighlight>
 == 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.
 To draw a polygon using the left mouse button—either drag a line or click points:

← Older revision		Revision as of 19:47, 3 September 2022
Line 16:		Line 16:
	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 start from the last table because it is the simplest. This is just a list of how many teams the map is designed for.

		+	[[File:Throne v1.minimap contrasty.jpg\|thumb\|High-contrast Throne mini-map showing the map's "rings."]]
	Let's take [http://zero-k.info/Maps/Detail/8162 Throne] map as an example. It has an outer ring with 7 starting areas, so it can be played as a 7-team <abbr title="free for all">FFA</abbr>. 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.)		Let's take [http://zero-k.info/Maps/Detail/8162 Throne] map as an example. It has an outer ring with 7 starting areas, so it can be played as a 7-team <abbr title="free for all">FFA</abbr>. 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.)

@@ Line 28: / Line 28: @@
 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 in-game, it's called "Startbox Editor" and is under the "For Developers" tab in the widget list (press {{key combo|Alt|F11}}, and don't touch anything else unless you know what you're doing).
+There is a widget which lets you draw the polygons in-game, it's called "Startbox Editor" and is under the "For Developers" section in the widget list (press {{key combo|Alt|F11}} to open the list, and don't touch anything else in there unless you know what you're doing).
 To draw a polygon using the left mouse button—either drag a line or click points:
@@ Line 51: / Line 51: @@
 Each of those tables is a team's start box. The config is an array of each team's start box data. The box data from the generator will go to a team's config entry. Like this:
-<syntaxhighlight lang="lua" highlight="3,4,5">local main_config = {
+<syntaxhighlight lang="lua">local main_config = {
+      {
           boxes = {
@@ Line 94: / Line 94: @@
           },
       },
- }</syntaxhighlight>
+}</syntaxhighlight>
 Of course, the start positions should match the areas, though they don't have to.
@@ Line 152: / Line 152: @@
       },
       -- more teams
- }</syntaxhighlight>
+}</syntaxhighlight>
 == Advanced stuff ==

@@ Line 1: / Line 1: @@
 == 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 by including a configuration file inside their map archive.
+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 by including a configuration file inside their map archive.
 == The config file ==
@@ Line 16: / Line 16: @@
 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.)
+Let's take [http://zero-k.info/Maps/Detail/8162 Throne] map as an example. It has an outer ring with 7 starting areas, so it can be played as a 7-team <abbr title="free for all">FFA</abbr>. 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:
@@ Line 22: / Line 22: @@
 This is mostly important for fancy FFA maps. Simple duel/teamgame maps will usually just have 2 as the only value here:
-<syntaxhighlight>local playercounts = {2}</syntaxhighlight>
+<syntaxhighlight lang="lua">local playercounts = {2}</syntaxhighlight>
 == The boxes ==
@@ Line 46: / Line 46: @@
 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 = {
+<syntaxhighlight lang="lua">boxes = {
       stuff
- },
+},</syntaxhighlight>
 Each of those tables is a team's start box. The config is an array of each team's start box data. The box data from the generator will go to a team's config entry. Like this:
- local main_config = {
+<syntaxhighlight lang="lua" highlight="3,4,5">local main_config = {
+      {
           boxes = {
@@ Line 65: / Line 65: @@
           },
       },
+}</syntaxhighlight>
 The layout is a normal Lua table so you can use all the usual table manipulation methods. For example, you could add more areas 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 start point in each box is mandatory. These points are also marked on people's UI as circles.
@@ Line 99: / Line 98: @@
 Of course, the start positions should match the areas, though they don't have to.
-== Putting these together ==
+== Team names ==
 You can give each team a name, alongside a shorter backup if the first one is too large. Here's how:
- <syntaxhighlight>{
+<syntaxhighlight lang="lua">{
       boxes = { stuff },
       startpoints = { stuff },
       nameLong = "Southwest",
       nameShort = "SW",
- }</syntaxhighlight>
+}</syntaxhighlight>
 It serves to identify the team, so while it's good to use something that describes placement, you can get creative. For example:
@@ Line 115: / Line 114: @@
 * 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, e.g. "Empire" vs "Dynasty"
+* for missions, it's good to use storyline names, e.g. "Empire" vs "Dynasty"
 == Summary ==
-Now just return the config table and the playercounts table.
+Now just return the ''config'' table and the ''playercounts'' table.
-<syntaxhighlight lang="Lua">return main_config, playercounts</syntaxhighlight>
+<syntaxhighlight lang="lua">return main_config, playercounts</syntaxhighlight>
 The exact format for the config table that should get returned is
-<syntaxhighlight>{
+<syntaxhighlight lang="lua">{
       { -- a single team's data
           boxes = {
@@ Line 156: / Line 155: @@
 == 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 <syntaxhighlight lang="Lua" inline>math.random</syntaxhighlight> without worry.
+The config has access to Spring Lua API, so it is possible to do a lot of dynamic things. In particular, you can use <syntaxhighlight lang="lua" inline>math.random</syntaxhighlight> without worry.
-You can make stuff dependent on the game mode. There are functions which return the game type, such as "<syntaxhighlight lang="Lua" inline>Spring.Utilities.Gametype.is1v1()</syntaxhighlight>".<!-- The full list USED TO BE here: https://github.com/ZeroK-RTS/Zero-K/blob/master/LuaRules/Utilities/teamFunctions.lua#L74-->
+You can make stuff dependent on the game mode. There are functions which return the game type, such as "<syntaxhighlight lang="lua" inline>Spring.Utilities.Gametype.is1v1()</syntaxhighlight>".<!-- The full list USED TO BE here: https://github.com/ZeroK-RTS/Zero-K/blob/master/LuaRules/Utilities/teamFunctions.lua#L74-->
-An important thing is that <syntaxhighlight lang="Lua" inline>#Spring.GetAllTeams()</syntaxhighlight> will return a wrong value due to fake technical teams and Gaia. Instead, use <syntaxhighlight lang="Lua" inline>Spring.Utilities.GetTeamCount()</syntaxhighlight> to get the real number of teams.
+An important thing is that <syntaxhighlight lang="lua" inline>#Spring.GetAllTeams()</syntaxhighlight> will return a wrong value due to fake technical teams and Gaia. Instead, use <syntaxhighlight lang="lua" inline>Spring.Utilities.GetTeamCount()</syntaxhighlight> to get the real number of teams.
 == Examples ==

@@ Line 1: / Line 1: @@
 == 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.
+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 by including a configuration file inside their map archive.
 == The config file ==
-The file which you need to include is
+The file that 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.
+For [[#Examples|examples]] see the bottom of this page.
 == Box counts ==
@@ Line 16: / Line 16: @@
 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.)
+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:
@@ Line 22: / Line 22: @@
 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}
+<syntaxhighlight>local playercounts = {2}</syntaxhighlight>
 == The boxes ==
@@ Line 29: / Line 28: @@
 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).
+There is a widget which lets you draw the polygons in-game, it's called "Startbox Editor" and is under the "For Developers" tab in the widget list (press {{key combo|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:
+To draw a polygon using the left mouse button—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.
+Once you draw a full loop, press the right mouse button to close it. Make sure the line does not cross itself. Finished polygons are a bit darker.
 [[File:Startbox API 2.jpg]]
@@ Line 43: / Line 42: @@
 [[File:Startbox API 3.jpg]]
-If you want to delete the last created polygon, press D.
+If you want to delete the last created polygon, press {{key press|D}}.
-Once you are satisfied with the area, press S. Now you can draw the area for another team.
+Once you are satisfied with the area, press {{key 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
@@ Line 51: / Line 50: @@
   },
-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:
+Each of those tables is a team's start box. The config is an array of each team's start box data. The box data from the generator will go to a team's config entry. Like this:
   local main_config = {
+      {
@@ Line 68: / Line 67: @@
+  }
-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 layout is a normal Lua table so you can use all the usual table manipulation methods. For example, you could add more areas 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.
+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 start point 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:
+Defining these is very simple. It's very similar to how start areas were defined. In game, you can hold Space over a point to see its coordinates. These are written down for boxes similarly to the areas:
- local main_config = {
+<syntaxhighlight>local main_config = {
+      {
           boxes = {
@@ Line 96: / Line 95: @@
           },
       },
+  }</syntaxhighlight>
 Of course, the start positions should match the areas, though they don't have to.
@@ Line 104: / Line 103: @@
 You can give each team a name, alongside a shorter backup if the first one is too large. Here's how:
+  <syntaxhighlight>{
       boxes = { stuff },
       startpoints = { stuff },
-      nameLong = "South-West",
+      nameLong = "Southwest",
       nameShort = "SW",
+  }</syntaxhighlight>
-It serves to identify the team so while it's good to use something that describes placement, you can get creative. For example:
+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"
+* "North", "Southeast"
 * "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"
+* for missions it's good to use storyline names, e.g. "Empire" vs "Dynasty"
 == Summary ==
 Now just return the config table and the playercounts table.
-  return main_config, playercounts
+<syntaxhighlight lang="Lua">return main_config, playercounts</syntaxhighlight>
 The exact format for the config table that should get returned is
+<syntaxhighlight>{
       { -- a single team's data
           boxes = {
@@ Line 154: / Line 153: @@
       },
       -- more teams
+  }</syntaxhighlight>
 == 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.
+The config has access to Spring Lua API, so it is possible to do a lot of dynamic things. In particular, you can use <syntaxhighlight lang="Lua" inline>math.random</syntaxhighlight> 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
+You can make stuff dependent on the game mode. There are functions which return the game type, such as "<syntaxhighlight lang="Lua" inline>Spring.Utilities.Gametype.is1v1()</syntaxhighlight>".<!-- The full list USED TO BE 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.
+An important thing is that <syntaxhighlight lang="Lua" inline>#Spring.GetAllTeams()</syntaxhighlight> will return a wrong value due to fake technical teams and Gaia. Instead, use <syntaxhighlight lang="Lua" inline>Spring.Utilities.GetTeamCount()</syntaxhighlight> to get the real number of teams.
 == Examples ==

@@ Line 19: / Line 19: @@
 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}
+<syntaxhighlight lang="lua">local playercounts = {2, 3, 5, 7}</syntaxhighlight>
 This is mostly important for fancy FFA maps. Simple duel/teamgame maps will usually just have 2 as the only value here:

@@ Line 60: / Line 60: @@
           -- more entries will go there later!
       },
-−
       -- another team's box data
+      {

@@ Line 158: / Line 158: @@
 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.
-An important thing is that #Spring.GetAllTeams() will return a wrong value due to fake teams and Gaia. Instead, use Spring.Utilities.GetTeamCount() to get the real number of teams.
+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
 == Examples ==