Levelgen Tutorial 01

Introduction

Welcome to the Bitfighter levelgen tutorial. Before we get started, here is a list of things you should know, and things you will learn:

Assumed Knowledge

This tutorial assumes you have read Programming Crash Course, and know what "variables" and "functions" are. It also assumes that you have basic to intermediate computer knowledge.

Outcomes

When finished with this tutorial, you should know:

• How to create and edit levelgen files.
• How to use levelgen files in levels you create.
• What the main() function is, and what you should put there.

Getting Started

Finding the Level Folder

The first step to writing levelgens is knowing where to put your .levelgen files. These files go in the "levels" directory of the Bitfighter install directory. To find out where this directory is, host a game or test a level, then hit F7 twice while in-game. This will take you to the Diagnostics screen. The line labeled "Level Dir:" will show the folder that you must put your .levelgen files in.

Editing .levelgen Files

You can edit .levelgen files in many text editors. A .levelgen file is just a normal .txt file with a special file extension. To open one with Notepad, right click the file, choose "Open With..." and select Notepad from the list. You can also open it from within Notepad if you choose "All Files (*.*)" from the dropdown in the Open dialog.

Notepad will work okay for your first few scripts, but eventually you will want to upgrade to an editor with more advanced features. Some good choices are Notepad++ for Windows, and GEdit or Komodo for Linux or Mac. This is the last time we will mention any specific editor.

Once you've chosen an editor, you're ready to begin!

Your First Levelgen

Now, create a new file in the Levels Folder and save it as tutorial.levelgen. Then, copy and paste the following code into your file, and save it:

function main()
 
   print("Hello, world!")
 
end

Next, open Bitfighter and start a new level in the editor (call it whatever you like). Press Escape to bring up the menu, choose Level Parameters, then scroll down to the "Levelgen Script" line. Type in tutorial then hit Escape and save the level. Now test the level.

If you followed directions exactly, you should be on a completely empty level with no company but the endless void of inner space. To see if your levelgen is being run by Bitfighter, you must open the Console. To do this in-game, press Ctrl+/ (Control and forward slash). A green console will drop down from the top of the screen. On the very bottom line you should see the phrase Hello, world!. If so, then congratulations on writing your first levelgen!

Note: You can close the console by pressing Ctrl+/ again.

Troubleshooting

If you didn't see the phrase in the console, here are some things to double check:

• You created tutorial.levelgen in the Level Folder
• You typed tutorial in the Levelgen Script line of the Level Parameters screen
• You copied and pasted the code above exactly
• Your text editor is saving the file as "plain text" (if available)

If you still need help, check the Troubleshooting page of the wiki

How It Works

function main()

Remember that functions are just named pieces of code which are meant to be used by other parts of a script or program. This first line defines a function called main which Bitfighter will call right before the level begins. Every levelgen you write should define a main function (it must be exactly called main -- it is case-sensitive). You should put all of your "start-up" code in this function, which we will do on the next line:

   print("Hello, world!")

Here we are calling a function named print. This function will display a value in the Console. We want to say hello to the world (Hello, world!), so we pass that as an "argument" to the function. The quotes will not be shown, they are just a way of telling the computer where our text begins and ends. Everything between the quotes will be printed.

end

Finally, we must end the main() function. If we do not add this line, the script will not run at all.

Conclusion

If you understand everything mentioned in the Outcomes section above, you are ready for Levelgen Tutorial 02.