Difference between revisions of "Levelgen Tutorial 02"

From Bitfighter
(Created page with "Category:Scripting = Introduction = Welcome to the Bitfighter levelgen tutorial. Before we get started, here is a list of things you should know, and things you will lear...")
 
Line 2: Line 2:
  
 
= Introduction =
 
= 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:
+
Welcome to Part 02 of the Levelgen Tutorial. In this lesson, we will learn how to create new game objects, and add them to the level.
  
−
== Assumed Knowledge ==
+
== Prerequisites ==
−
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.
+
You should have completed [[Levelgen Tutorial 01]]. Specifically, you should know:
 +
* How to create and use levelgen files in a level.
 +
* What the <tt>main()</tt> function is for.
  
 
== Outcomes ==
 
== Outcomes ==
 
When finished with this tutorial, you should know:
 
When finished with this tutorial, you should know:
−
* How to create and edit levelgen files.
+
* How to create a new <tt>TextItem</tt> and add it to the game.
−
* How to use levelgen files in levels you create.
+
* How to set the text of a <tt>TextItem</tt>.
−
* How to write a simple levelgen.
+
−
* How to create new TextItem and add it to the game.
+
  
−
= Getting Started =
+
= Code =
  
−
== Finding the Level Folder ==
+
Save the following code as a .levelgen file, and create an empty level which uses it.
−
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 [http://notepad-plus-plus.org/download/ Notepad++] for Windows, and [http://projects.gnome.org/gedit/ GEdit] or [http://www.activestate.com/komodo-edit/downloads 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 <tt>tutorial.levelgen</tt>. Then, copy and paste the following code into your file, and save it:
+
  
 
<source lang="lua">
 
<source lang="lua">
 
function main()
 
function main()
  
−
  -- First, create a new TextItem and name it `textItem`
 
 
   local textItem = TextItem.new()
 
   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!")
 
   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)
 
   levelgen:addItem(textItem)
  
Line 46: Line 28:
 
</source>
 
</source>
  
−
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 <tt>tutorial</tt> then hit Escape and save the level. Now test 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!
  
−
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!
+
If it didn't work, check the [[Troubleshooting]] page of the wiki.
−
 
+
−
== Troubleshooting ==
+
−
If you didn't see the TextItem, here are some things to double check:
+
−
* You created <tt>tutorial.levelgen</tt> in the Level Folder
+
−
* You typed <tt>tutorial</tt> 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 =
 
= How It Works =
−
Lines beginning with <tt>--</tt> (two dashes) are comments, which are ignored by the computer, so we will skip those lines here.
 
−
 
 
<source lang="lua">
 
<source lang="lua">
 
function main()
 
function main()
 
</source>
 
</source>
−
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 <tt>main</tt> which Bitfighter will call right before the level begins. Every levelgen you write should define a <tt>main</tt> function (it ''must'' be exactly called <tt>main</tt> -- it is case-sensitive). You should put all of your "start-up" code in this function.
+
As in every levelgen, we put the main chunk of code in the <tt>main</tt> function.
  
 
<source lang="lua">
 
<source lang="lua">
 
   local textItem = TextItem.new()
 
   local textItem = TextItem.new()
 
</source>
 
</source>
−
Here we are creating a new TextItem and storing it into the variable <tt>textItem</tt> for later use.
+
Here we are creating a new TextItem and storing it into the variable <tt>textItem</tt> for later use. Remember that variables can refer to anything in Lua, whether it be a number, a string of text, a game object, or "nothing". Here, it's referring to our new TextItem, which is a game object.
 +
 
 +
Now we will set the text of this TextItem to say hello:
  
 
<source lang="lua">
 
<source lang="lua">
 
   textItem:setText("Hello, world!")
 
   textItem:setText("Hello, world!")
 
</source>
 
</source>
−
This line sets the text displayed by <tt>textItem</tt>. 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. <tt>setText</tt> only takes one argument: a string to set the displayed text to.
+
 
 +
This line means "set the text of <tt>textItem</tt> to <tt>Hello, world!</tt>".
 +
 
 +
The part before the colon (the <tt>:</tt> sign) is our variable name (<tt>textItem</tt>). The part after it is the function we're calling (<tt>setText</tt>).
 +
 
 +
Again, we are passing some text as the argument to a function. This time, it is <tt>setText</tt> instead of <tt>print</tt>, but as you can see there is not much of a difference in how we write it.
 +
 
 +
Next, we must actually add our TextItem to the game:
  
 
<source lang="lua">
 
<source lang="lua">
 
   levelgen:addItem(textItem)
 
   levelgen:addItem(textItem)
 
</source>
 
</source>
−
After creating our TextItem and setting it up as we'd like, we must add it to the game. To do this, we call <tt>levelgen:addItem</tt>. <tt>levelgen</tt> 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. <tt>levelgen:addItem</tt> takes one argument, the object to add to the game. In this case, it is our `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 <tt>levelgen:addItem</tt>. <tt>levelgen</tt> 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. <tt>levelgen:addItem</tt> takes one argument, the object to add to the game. In this case, it is our TextItem instace, `textItem`.
  
 
''Note:'' If you do not call <tt>addItem</tt> on objects you create with <tt>.new()</tt>, they will not appear in-game.
 
''Note:'' If you do not call <tt>addItem</tt> on objects you create with <tt>.new()</tt>, they will not appear in-game.
Line 87: Line 67:
 
end
 
end
 
</source>
 
</source>
−
Finally, we must end the <tt>main()</tt> function. If we do not add this line, the script will not run at all.
+
And again, we end our <tt>main</tt> function.
  
 
= Conclusion =
 
= Conclusion =
−
If you understand everything mentioned in the Outcomes section above, you are ready for [[Levelgen Tutorial 02]].
+
If you understand everything mentioned in the Outcomes section above, you are ready for [[Levelgen Tutorial 03]].

Revision as of 11:44, 9 August 2013


Introduction

Welcome to Part 02 of the Levelgen Tutorial. In this lesson, we will learn how to create new game objects, and add them to the level.

Prerequisites

You should have completed Levelgen Tutorial 01. Specifically, you should know:

  • How to create and use levelgen files in a level.
  • What the main() function is for.

Outcomes

When finished with this tutorial, you should know:

  • How to create a new TextItem and add it to the game.
  • How to set the text of a TextItem.

Code

Save the following code as a .levelgen file, and create an empty level which uses it. 

function main()
 
  local textItem = TextItem.new()
  textItem:setText("Hello, world!")
  levelgen:addItem(textItem)
 
end

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!

If it didn't work, check the Troubleshooting page of the wiki.

How It Works

function main()

As in every levelgen, we put the main chunk of code in the main function. 

  local textItem = TextItem.new()

Here we are creating a new TextItem and storing it into the variable textItem for later use. Remember that variables can refer to anything in Lua, whether it be a number, a string of text, a game object, or "nothing". Here, it's referring to our new TextItem, which is a game object.

Now we will set the text of this TextItem to say hello: 

  textItem:setText("Hello, world!")

This line means "set the text of textItem to Hello, world!".

The part before the colon (the : sign) is our variable name (textItem). The part after it is the function we're calling (setText).

Again, we are passing some text as the argument to a function. This time, it is setText instead of print, but as you can see there is not much of a difference in how we write it.

Next, we must actually add our TextItem to the game: 

  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 instace, `textItem`.

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

end

And again, we end our main function.

Conclusion

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

Retrieved from "http://bitfighter.org/wiki/index.php?title=Levelgen_Tutorial_02&oldid=5216"