Levelgen Overview

Levelgens are a little different. While the entire purupose of a bot is to actively participate in a game, many levelgens will not stick around after the level has been loaded. For a basic levelgen, the entire script might be contained in the main() function – it might create some items, and do nothing more.

If a level has a levelgen script, its main function is executed as the level is loaded, after all objects defined in the level file have been created. Therefore a levelgen can act upon those objects, either altering them, deleting them, or by adding completely new objects.

Levelgens can also subscribe to events; their event handlers will be called throughout the game as events are fired.

Unlike robots, levelgens are not automatically subscribed to the Tick event.

"Hello World" Levelgen recipe

1. Start the Bitfighter level editor.
2. Open the second diagnostics screen to find the Bitfighter LevelDir by pressing [F7] twice.
3. Open your favorite text editor and create the following skeleton script:

   function main()     -- Gets run when level is loaded, before game starts
       print("Hello World!")
   end

4. Save it in the scripts folder as "hello_world.levelgen" (the .lua extension will also work).
5. Create a barebones level in the editor.
6. Edit the level settings in the Game Params Editor [F3].
7. Set the Levelgen Script option to "hello_world" (no need to enter the extension).
8. Press [Esc] to return to the editor, and [Esc] again to get to the Main Menu. Select the Test Level option.
9. Open the console ([Ctrl-/]) and you should see the text "Hello World!".

You can build on this script by expanding the main() function, or by subscribing to events and adding event listeners to respond to them. See Subscribing to Events for more information.

A Slightly More Interesting Example

You can do some pretty neat things with even a basic levelgen script, such as add objects to levels.

Modify your hello_world script to look like this:

function main()
    -- print("Hello World!")
    radius = 200
    items = 10
 
    for i = 0, items - 1 do
        resourceitem = ResourceItem.new(        -- Create the item
            point.new(radius * math.cos(i * 2 * math.pi / items), radius * math.sin(i * 2 * math.pi / items))
        )
        levelgen:addItem(resourceitem)          -- Add it to the level
    end
end

Now when you start your level, you should see a ring of resource items!

If you don't see them, the script might be crashing. Errors are logged to the console, so be sure to check there when something isn't working. To run your script again, quit the game and restart it.