They Are Billions

They Are Billions

120 ratings
They Are Billions - Official Workshop Guide
By Numantian Games and 2 collaborators
This is a quick guide to help the players to create custom leves for They Are Billions using the official game editor application TABEditor.
Launch the Editor
There are two ways to launch the Editor:
  • From the game main menu, go to More => Launch Editor
  • Or just press and hold the SHIFT key when starting the game and the editor will be launched automatically.
Creating a Custom Level

New Custom Level
From the Editor menu click on New to create a new project.
Fill out the basic info of the project (level name, description...).
You can also select a preview image for your level (used in the game and in the Workshop).

Select the difficulty you think it is appropriated for your level. It will affect the final score factor.

Saving Projects
From the game menu use the options Save or Save As to save the project. Projects should be saved in this folder:
Documents\My Games\They Are Billions\Projects

IMPORTANT: Create a folder for every project under the Projects Folder. When submitting a custom level, all assets files (pngs, jpgs, audio) in the same folder as the project (.TABProject) will be copied to the custom level. So create a separated folder for every project to avoid mixing assets between them. For example if you create a custom level called "Mega Swarm", project files should be as:
"Documents\My Games\They Are Billions\Projects\Mega Swarm\Mega Swarm.TABProject"
"Documents\My Games\They Are Billions\Projects\Mega Swarm\Header.png"
"Documents\My Games\They Are Billions\Projects\Mega Swarm\EventWorkersOnStrike.png"

TIP: Save your project regularly. As the Editor is still in beta it could experience some issues.

IMPORTANT: First check all the Tooltips for more info
In the editor you will find some yellow boxes with this symbol [?]. Position the mouse pointer over them to get a quick help about that section.
Map Creation
Creating the Map
First select the map properties: Theme, difficulty and type of map generation.

You can select a specific theme for the level or let the player choose one when the game starts.
In this case the score factor will be affected by the type of map.

Map Generation
You have two options for creating the map: Manual and Random.

Random Creation
When Random Generation is chosen, a common Survival Map will be generated as the player starts a new game. It will be generated with the Theme and Infected Population values selected.
In this option you just need to specify the Level Events (swarms...) and Narrative (scripts).
This is a very useful option to create a different Survival challenge experience for the player.
If you have selected a random map you can skip the rest of this section.

Note: In random generated maps, only the geography and infected population will be created in the same way as in a normal Survival Game. BUT, the level events (swarms, victory conditions,...) won't be created so you have to configure that part at your own.

Manual Creation
In this mode you can manually create all the map (geography, entities...).
There are two ways to create maps, the Entities Mode, where you can create and edit manually entities on the map, and the Painter Mode, which is a very fast way to draw the geography and infected population directly on the map.

Entities Management Section

Here you can create entities manually and edit their properties.
Every element in the game is consider an entity, like a unit, building, ornament...
To edit the map geography or add infected population very fast use the Painter Mode.

Entities List
Here you can manage the entities you have manually added to the map.
You can show all the entities or filter them by the selected template.

- Left Click => Select an entity.
- Double Click => Select an entity and center it in the map.
- Right Click => Display the context menu.
- Key [Delete] => Delete the selected entity.

NOTE 1: The Command Center is essential in a survival game, so it cannot be deleted or duplicated.
NOTE 2: Empty maps come with default entities generators (N,S,E,W) to make it easier to define the swarms, but you can edit them or replace them as you like.

Entities can have several configuration parameters, use the Edit option in their context menu to see/edit their properties. For example, the identifier of a Generator, make a unit veteran...

Creating Entities
Click here to add an entity of the selected template to the map.
You can easily create entities by using CONTROL + LEFT CLICK directly on the map.

Map Editor Management in Entities Mode
Here are the main actions you can perform directly on the map editor.

- Press LEFT CLICK over an entity to select it.
- You can move an entity directly by clicking and dragging the green circle of the selected unit .
- Press DOUBLE CLICK to select the entity and its template.
- Press RIGHT CLICK and drag the mouse to move the editor camera.
- Press RIGHT CLICK on an entity to display its context menu.
- Press [Delete] to delete the selected entity.
- Press [TAB] to rotate the selected entity if it is rotatable (like gates).

Painter Mode

With the painter mode you can very easy and fast edit the following aspects of the map:
- Geography: Mountains, forests, terrains, minerals...
- Infected Population

To paint on the map you just have to select the pencil and draw directly on the map using the [LEFT BUTTON].
- There are different layers for every system: Terrains, objects, infected.
- Every layer has its own pencil to draw on the map.
- You can show/hide the different layers by checking on the left of every layer.
- You can also select the width and shape of the pencil.
- To erase parts already drawn over a layer use the [ALT] + [LEFT CLICK] combination.

Once you return to the Entities Mode the map will be updated automatically, it can take a few seconds.

Map Editor Management in Painter Mode
These are the main actions you can perform directly on the map editor.

- Press LEFT CLICK and drag to draw with the selected pencil.
- Press RIGHT CLICK and drag the mouse to move the editor camera.
- Press LEFT CLICK + ALT and drag to erase the current layer.

Tips and Recommendations
- First work on the geography of the map. And once you are happy with it, start with the manual entities.
- Leave the infected population for the end. Too many infected on the map will severely impact on the performance of the Editor, so use the Infected Pencils once you have worked in all of the other parts.

Level Events
Level Events

The Events System is an essential part of a game level. The Events are used to:
  • Trigger infected swarms.
  • Define when the game is won or lost.
  • Execute custom scripts.
  • Special actions like: Show the full map or send all infected to the Colony.

Add and remove events
Click the + and - buttons to add or delete events on the list.

Event Scheduling
For every event, you must set:
  • When (which day) the event is triggered.
  • Can be triggered several times or just one?
  • What happens when the event is triggered?

To define an event fill the properties of the event on the right. Every field has its own help that it is displayed on the bottom panel.

TIP: To Expand or Collapse a category or property use [DOUBLE CLICK] on the item label.

Time Syntax
The game time can be specified in days or hours (in game colony time).
  • To use days just add the 'd' character to the number: '4d' = 4 days.
  • To use hours use the 'h' character: '8h' = 8 hours.
  • You can also specify things like 2 days and 8 hours: '2d 8h'.

Generators Syntax
When you specify that an event is generating units (infected) when triggered,
you must specify the generator(s) where the units will be generated from.
The generators are defined in the Map section. By default there are 4 generators created: N, S, E, W
You just have to write the name ID of the generator followed by the AND operator or the OR operator.
When using the OR operator the game will choose randomly which generator to use when the event is triggered.
  • Units must generate just on the generator N: 'N'
  • Units must generate on the generators N and S: 'N and S'
  • Units must generate randomly in one of the four generators: ' N or S or E or W'
  • Units must generate from the generators N and S or the E and W: 'N and S or E and W'

Although generally the Events are used to generate swarms, you can also use them for triggering custom scripts (show messages, give resources to the colony...). See the Scripts section for more info.

Game Narrative

You can enhance your level adding some narrative that will be displayed to the players during specific parts of the game.

Here you can configure the scripts for the main game events:
  • When the game starts.
  • When the game is won.
  • When the game is lost.

It is recommendable to at least display a message in those events to present the level to the player.

  • To trigger scripts during specific moments of the game use the Events System.
  • To trigger scripts when a unit reaches a specific area use the MapMessageEvent entity in the Map Editor.

For more information about the Scripting please check the Scripts Section.
Custom Commands

In this section you can create a custom command button for the Command Center. It will be displayed as a button in the same way as the other commands.
You can configure here the script to execute when the players click it.
This is a useful too that allows the player to interact with your level in the way you like. It can for example, open a commerce center, a dialog to talk to other colonies, a economy or politics managing center...

To show the button you just need to assign an identifier. If it is empty the button won't be displayed.
As any other command you have also several options more to configure it:

Name and Description
Custom name and description to display on the help tooltip of the button.

You can configure via ZXCode condition when the button is visible.

You can configure via ZXCode condition when the button is enabled or disabled when it is visible. Also you can display a custom text for when it is disabled.

Display Counter
You can display a counter by setting an expression that returns a number. You can do this if you for example wants to limit the uses of the button and want to show how many uses are remaining.

Resources Cost
You can set a resources cost that will be payed when the command is activated. The button will be automatically disabled when the player don't have enough resources to use it.

A Script is a set of actions that are executed in order. The scripts can be triggered by a Level Event or other special game events (see Game Narrative).

Using scripts you can enhance a lot your level, you can create a very rich story, and special new mechanisms or surprises to the player. The number of available actions will be increased in future updates. These are some of the actions you can currently use:
  • Display a message to the player.
  • Give / Remove resources to the Colony.
  • Give bonus buildings or units to the Colony.
  • Grant technologies to the Colony.
  • Infect a random house.
  • Generate units from a generator.
  • Display a set of options to be chosen by the player.
  • Execute random actions.

Creating and Managing the Script Actions
Every type of action has their own set of parameters.
  • First, select the type of action you want to add and click on the '+' button.
  • Use the '-' button to delete the selected action.
  • Use the ▲ and ▼ buttons to change the order of the actions inside the same block.

Nested Actions
Some actions, like the Random Action, the Block or the Select Option, can have nested (children) actions. When you create a new action and you have selected an action that can have children actions it will be created inside the selected action.
  • Use the ◀ button to extract the selected action from their current block.
  • Use the ▶ button to put the selected action in the next/previous action block.

Action Properties
Every action has its own properties. A help message will be displayed under the action properties to describe every parameter of the action.

There are two actions for managing Loops: Loop and Exit Loop. The Loop execute indefinitely their children actions until a Exit Loop action is executed. Useful to create complex menus with Back / Exit options, or dialog systems.
Note: Be careful with using Loops. If you forget to add the Exit Loop action, the script never finishes and you have to close the game with ALT+F4.
Testing your Level
Before publishing your level you should test it locally. This is very easy. Just use the menu option "Generate Level", and the custom level will be created in this folder:
Documents\My Games\They Are Billions\CustomLevels

Then Start They Are Billions and, in the game main menu, go to: New => Custom Level.

In the next screen you will find all the levels you have subscribed to [STEAM], and all the levels inside the folder CustomLevels [LOCAL].

You can start the game from there and play it normally to test the level. You can also save your game and load it later from the Continue option menu.

The map, level events and scripts are all stored in the save game file, so if you modify them in the Editor you will need to start a new game to reflect the changes.
Publishing your level in the Workshop
Before publishing your level, please test it locally to ensure that everything works as expected. See the section "Testing your Level".

Publishing the Custom Level on Steam

  • Make sure that Steam Client is running and it's connected to Internet.
  • You can select the visibility of your workshop item: Public, Hidden or Friends.
  • Press the button publish to upload your level. You can specify change log notes if you like.
  • Once the item is uploaded you can access your Steam Workshop page of that item.
  • There you can add more images, description, guides, discussions... as with any other Steam Workshop Item.
  • When the item is published publicly it will become visible for all the community, and any player will be able to subscribe to your level to play it.
Strings, Localization & Random Texts

You can manage the strings used in your custom level in a more efficient way, and also support localization to different languages. This is very useful for levels with an extensive narrative.

For example, you can have several messages that use exactly the same strings (Ex. "A gift from your neighbors!"). If you wish to change that text you have to change it in all the places where that text appear. With this method, you just write an identifier (Ex. "@GiftTitle") and the real text will be stored in a separated CSV file.

Put your texts in a CSV file
Create a text file called Strings.csv in the same folder as your project is. When submitting your level this file will be included among all other assets.
You can use Excel or any other spreadsheet application or simply the Notepad to edit your Strings.csv file.

The CSV Structure
  • A CSV file is just a text file formatted like a table. Every line is a row, and every column is separated by a ';' or 'tab' characters.
  • The first row are the column names.
  • Use ID for your first column. In this column you have to write the same identifiers as the ones used in your custom level. We recommend to use the @ symbol to make it more clear.
  • The rest of the columns are the languages in which you want to localize your level. You can use one or as many languages as the ones available in the game. Use the country code for the name of the column.

For example if you wished to support English and Spanish languages the CSV would be something like:
ID; EN; ES @GiftTitle; A gift from your neighbors!; ¡Un regalo de tus vecinos! @Welcome; Welcome to the colony; Bienvenido a la colonia

In all texts introduced in the scripts when the game finds one of this identifiers it will be replaced with the text that corresponds to the player language (if available), or else it will use the English entry (if available) or if not the first language available. That includes all texts in script actions and also the level name and description of the info tab, as they will appear also in the player language on Steam.

Language Codes
  • English = EN
  • Spanish = ES
  • German = DE
  • Russian = RU
  • French = FR
  • Korean = KO
  • Italian = IT
  • Japanese = JP
  • Brazil = BR
  • Portuguese = PT
  • Polish = PL
  • Simplified Chinese = CHS
  • Traditional Chinese = CHT

Random Texts
Perhaps you wish to display random texts to enrich the narrative. To do that easily take the entry you wish to add more texts, for example, "@WelcomeText", and add multiple entries with IDs starting by the same string. For Example: "@WelcomeText1, @WelcomeText2,...". When the game find several entries starting by the same ID it will take a random one.

With this method you can save a lot of time, instead of creation lots of random actions in your scripts just to offer different texts, you can just create one and add multiple entries to the csv file.

With random texts you can enrich the narrative a lot surprising the player in every new game. For example, periodic rumors from the Inn, news from other colonies, colony events,...

Recommendations: Be gentle with your audience
  • English language should be mandatory. Think that most players from non English countries can understand English quite well and enjoy your level.
  • If your native language is included in the game (for example Italian), add it too to your level apart from English. It will be very appreciated by players native to that language.
  • Chinese, Japanese and Korean, can be challenging languages to translate to, but even a automated translation to those languages can be better than nothing, and your level could also be enjoyed by those players.

Advanced: Variables & Functions (ZXCode)
Note:This section is for advanced users.

With the ZXCode language you can add much more functionality to the scripts and events. You specify complex conditions for triggering actions or events and also manage your own game variables.

All actions have now two new parameters: Condition and Execute Code.
Events have the Condition parameter too.

With these new elements you can implement much more complex gameplay mechanisms for your levels. Examples: A political system tree, managing the happiness of the colonists, choices and consequences of the player decisions, managing the commerce with foreign colonies, custom goals to win or lost the game...

To achieve this we have created a simple language with similar syntax to c#, c or c++. Example:
MyVariable = Colonists + Workers * 10; (Count(Unit) >= 100 && Count(Wonder)>=3) || IsDead(Bob)

In the code you can reference any game variable or function and your own custom variables.

List of Game Variables & Functions
In the page it is listed all the variables and functions. Select one to see the help of the selected element.
Also you have the list of symbols for the entities as some functions needed. For example, fore the function Count (Entity), you have to pass the entity type by choosing one of the available in the symbol list. Example: "Count(Ranger)" it returns the number of rangers alive in the game.

Note: The list of variables and functions will expand with future updates, check the list from time to time to see the changes.

Specifying conditions for triggering actions or events
The events and the actions now have a new parameter called Condition (ZXCode) where you can write a custom condition using ZXCode.
If the condition of an action is false then the action and their children won't be executed.
For the conditions you can reference any function, number, user variable or game symbol and use any combination with operators and parenthesis.

Operators available are:
  • ==
    Comparator Equal: "Days == 100". Only true if the current day is 100.
  • !=
    Comparator Not Equal: "Days != 100". True for all days except 100.
  • >
    Comparator Greater than: "Days > 100". True for days 101, 102...
  • >=
    Comparator Greater than: "Days >= 100". True for days 100,101,102..
  • <
    Comparator Lesser than: "Days < 100". True for days 99, 98,...
  • <=
    Comparator Lesser or equalthan: "Days <= 100". True for days 100, 99, 98...
  • &
    Logical And: "Days>=100 & Days<=103". True for days: 100, 101, 102,and 103.
  • |
    Logical Or: "Days<=5 | Days ==100". True for days: 0,1,2,3,4,5 and 100.
  • !
    Logical Not: "!IsDead(Bob)". True if Bob is not dead.
  • +, -, *, /
    Arithmetic operators : "Gold > (Workers * 2 +10)". True if the gold reserves are greater than the number of workers multiplied by 2 plus 10.

    • Win the game when the colony has 10000 populations: Just create an event, check the Game Won parameter and set the condition:
      Colonists >= 10000
    • Give a bonus to the player when have 100 soldiers and 100 snipers in their army:
      (Count(Soldier) >= 100) & (Count(Sniper) >= 100)
    • Loose the game if the Soldier hero with NameID ="Bob" is dead:
    • Win the game when all the Doom Buildings have been destroyed:
      Count(DoomBuilding) == 0
    • A merchant sells a Titan to the colony by 1000 gold and 50 iron but only if you have the resources :
      Gold >= 1000 & Irons >= 50

    Declaring and using custom variables
    In this page you can create your own variables that you could refer in your scripts ZXCode.
    Use the [+] and [-] buttons to add or remove variables.
    To edit a variable in the list, make double click on it.
    You can modify their values in the Execute Code parameter of the actions.
    Every sentence must end with ';' character:
    Happiness += 5; Sadness -=5; EndGameWon();

    For example imagine you wish to control the happiness of the colonists, you just need to create a variable "Happiness" with an initial value of 10 (for example).
    And then you show a pack of options that depending on the selected one this value will change:
    • Menu Option: "Put children to work (Workers+100)"
      Happiness = Happiness - 5; // or just: Happiness -= 5;
    • Menu Option: "Deliver extra food for the colonists (Food -50)"
      Happiness = Happiness + 2; // or just: Happiness += 2;
    • Menu Option: "Increase colonists tributes (Gold+1000)"
      Happiness = Happiness - 2; // or just: Happiness -= 2;
    And in future actions you can use the Happiness in the conditions of other actions, for example:
    • Condition:
      Happiness > 20
    • "Your happy colonists wants to build a Victorious in your honor." (Gift: Victorious Wonder)
    • Condition:
      Happiness < 0
    • "Your sad colonists hate their commander and leave the colony." (Workers-200, Colonists-500)

    Using ZXCode expressions in game texts
    You can include ZXCode expressions in the game texts (window messages, options...). To do that just use the code inside {} characters. For example in window messages Texts or Titles.

    "The number of walls is: {Count(Wall)}."
    "The Colony Happiness Level is: {Happiness}." //Happiness is a user variable previously declared.
< >
TheSkeleZ 16 hours ago 
Gomez, i did not find anything there that could answer my question. What i am trying to do is make so you can only win if you have 1000 colonists and 5 advanced farms.
Gomez  [author] Jun 5 @ 1:42am 

@TheSkeleZ please check this specific part of the forum for your kind of questions

TheSkeleZ Jun 4 @ 10:05pm 
How do i make custom win conditions please i really need help i cant finish my map without them, also why are there so few cosmetic items like why no destroyed buildings or stuff im sorry but please i need to know how to make win condidtions.
596684322 May 15 @ 8:50pm 
Gomez  [author] Feb 13 @ 1:08am 
Hello @Jacky_Lin. What you say is have been given as suggestion for the next Map Editor update. Dev Team is now working in this update.

I would like to recommend you to post in this part of the forum made specifically for Map Editor quetions. Check here --->>

Thanks in advance.

Jacky_Lin Feb 12 @ 8:28pm 
Is there a way to make it generate a random map similar to the survival mode, and then modify it manually? I don't want to go from no drawing to having, but I want to modify it on an existing random map.
Gomez  [author] Dec 26, 2019 @ 11:45pm 

We have a specific forum made for this kind of questions. Check here --->>

Post your doubts there.

Thanks in advance.

leggo Dec 21, 2019 @ 8:38pm 
how can i make my custom map generate human units (soldiers, rangers, snipers, etc) the same way as if i use a unit generator to spawn a zombie horde?
ps: is any reason why you can't spawn mutants in map editor?
Gomez  [author] Dec 9, 2019 @ 10:54pm 

@corbusier please, open a thread in the proper part of the forum made for bug reporting.

Check here --->>

Thanks in advance.

corbusier Dec 9, 2019 @ 8:06pm 
I am missing my map editor, cannot launch and the editor folder is empty.