Revision as of 00:58, 9 August 2013

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.
• How to write a simple levelgen.
• How to create and add a TextItem to the game.

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()
 
  -- First, create a new TextItem and name it `textItem`
  local textItem = TextItem.new()
 
  -- Then set textItem's text so that it says "Hello, World!"
  -- (it doesn't show the quotes)
  textItem:setText("Hello, world!")
 
  -- This step is important: any item created in a levelgen must then be added
  -- to the game using `addItem`
  levelgen:addItem(textItem)
 
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 everything went well you should see a text item that says "Hello World!" right in the center of your empty level. Behold, the magic of levelgens!

Troubleshooting

If you didn't see the TextItem, 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

Lines beginning with -- (two dashes) are comments, which are ignored by the computer, so we will skip those lines here.

function main()

Remember that functions are just named pieces of code which are meant to be used by other code. 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.

  local textItem = TextItem.new()

Here we are creating a new TextItem and storing it into the variable textItem for later use.

  textItem:setText("Hello, world!")

This line sets the text displayed by textItem. The part before the colon (the : sign) is our variable name. The part after it is the function we're calling on it. Anything between the parentheses is called an argument. setText only takes one argument: a string to set the displayed text to.

  levelgen:addItem(textItem)

After creating our TextItem and setting it up as we'd like, we must add it to the game. To do this, we call levelgen:addItem. levelgen is a variable which is predefined by Bitfighter when it runs a levelgen script. This variable represents the currently running script, and provides functions for doing things to the game. levelgen:addItem takes one argument, the object to add to the game. In this case, it is our `textItem`.

Note: If you do not call addItem on objects you create with .new(), they will not appear in-game.

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.