Editing Startbox API
Jump to navigation
Jump to search
Warning: You are not logged in. Your IP address will be publicly visible if you make any edits. If you log in or create an account, your edits will be attributed to your username, along with other benefits.
The edit can be undone. Please check the comparison below to verify that this is what you want to do, and then save the changes below to finish undoing the edit.
Latest revision | Your text | ||
Line 1: | Line 1: | ||
== Start boxes == | == Start boxes == | ||
− | Each team has a defined starting area in which its players can spawn their commanders—these are called | + | 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 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 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] | ||
Thus, the possible team counts are 2, 3, 5, and 7. Let's define a Lua table for that: | Thus, the possible team counts are 2, 3, 5, and 7. Let's define a Lua table for that: | ||
Line 23: | Line 22: | ||
This is mostly important for fancy FFA maps. Simple duel/teamgame maps will usually just have 2 as the only value here: | This is mostly important for fancy FFA maps. Simple duel/teamgame maps will usually just have 2 as the only value here: | ||
− | <syntaxhighlight | + | <syntaxhighlight>local playercounts = {2}</syntaxhighlight> |
== The boxes == | == 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. | 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" | + | 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 using the left mouse button—either drag a line or click points: | To draw a polygon using the left mouse button—either drag a line or click points: | ||
Line 47: | 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 | 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 | stuff | ||
− | }, | + | }, |
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: | 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 = { | |
{ | { | ||
boxes = { | boxes = { | ||
Line 66: | Line 65: | ||
}, | }, | ||
}, | }, | ||
− | } | + | } |
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 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 == | + | |
+ | === 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. | 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 95: | Line 95: | ||
}, | }, | ||
}, | }, | ||
− | }</syntaxhighlight> | + | }</syntaxhighlight> |
Of course, the start positions should match the areas, though they don't have to. | 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: | You can give each team a name, alongside a shorter backup if the first one is too large. Here's how: | ||
− | <syntaxhighlight | + | <syntaxhighlight>{ |
boxes = { stuff }, | boxes = { stuff }, | ||
startpoints = { stuff }, | startpoints = { stuff }, | ||
nameLong = "Southwest", | nameLong = "Southwest", | ||
nameShort = "SW", | 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: | 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 115: | ||
* real-world style maps could have names like "Russia" or "America" | * real-world style maps could have names like "Russia" or "America" | ||
* asymmetric maps can use landmarks, for example "Lake" vs "Desert" | * asymmetric maps can use landmarks, for example "Lake" vs "Desert" | ||
− | * for missions | + | * for missions it's good to use storyline names, e.g. "Empire" vs "Dynasty" |
== Summary == | == Summary == | ||
− | Now just return the | + | Now just return the config table and the playercounts table. |
− | <syntaxhighlight lang=" | + | <syntaxhighlight lang="Lua">return main_config, playercounts</syntaxhighlight> |
The exact format for the config table that should get returned is | The exact format for the config table that should get returned is | ||
− | <syntaxhighlight | + | <syntaxhighlight>{ |
{ -- a single team's data | { -- a single team's data | ||
boxes = { | boxes = { | ||
Line 153: | Line 153: | ||
}, | }, | ||
-- more teams | -- more teams | ||
− | }</syntaxhighlight> | + | }</syntaxhighlight> |
== Advanced stuff == | == 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=" | + | 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=" | + | 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=" | + | 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 == | == Examples == |