Difference between revisions of "Modding:Tutorial"

From DoomRL Wiki

Jump to: navigation, search
(started to work on tutorial: I'm not actually near any code so this is all from memory and will be really bad: will edit/add to later.)
 
(new tutorial!)
 
(26 intermediate revisions by 3 users not shown)
Line 1: Line 1:
−
{{Incomplete}}
 
 
Welcome to the DoomRL modules tutorial. The objective of this guide is to explain how to develop your own modules for DoomRL as easily and as accurately as possible: therefore, its scope is fairly limited and will only cover basic techniques in customizing objects, maps, and game events. However, it is written at the level of one who has little to no background knowledge of programming languages, and so is ideal for a player who doesn't understand the fundamentals of scripting. Anyone who has the ambition to create a unique and enjoyable game out of the DoomRL engine should use this as a tool to get started.
 
Welcome to the DoomRL modules tutorial. The objective of this guide is to explain how to develop your own modules for DoomRL as easily and as accurately as possible: therefore, its scope is fairly limited and will only cover basic techniques in customizing objects, maps, and game events. However, it is written at the level of one who has little to no background knowledge of programming languages, and so is ideal for a player who doesn't understand the fundamentals of scripting. Anyone who has the ambition to create a unique and enjoyable game out of the DoomRL engine should use this as a tool to get started.
  
 
Modifying DoomRL content is done through lua, a scripting language designed to communicate with a variety of other computer languages. (You can find out more about lua by following [http://www.lua.org/ this link].) As such, a great deal of what can be done for the purpose of DoomRL modding is handled by the API, or application programming interface, which allows a modder to issue commands that are sent to the DoomRL engine (written in Pascal). The formatting and syntax is relatively simple and flexible, so there are a number of ways to write code in lua that will produce the same outcome. We will use a particular format, although alternatives will be explained as they come up.
 
Modifying DoomRL content is done through lua, a scripting language designed to communicate with a variety of other computer languages. (You can find out more about lua by following [http://www.lua.org/ this link].) As such, a great deal of what can be done for the purpose of DoomRL modding is handled by the API, or application programming interface, which allows a modder to issue commands that are sent to the DoomRL engine (written in Pascal). The formatting and syntax is relatively simple and flexible, so there are a number of ways to write code in lua that will produce the same outcome. We will use a particular format, although alternatives will be explained as they come up.
 +
 +
Writing lua code yourself is done in a text editor. What text editor you use depends on your operating system: for Windows, it is Notepad. It is suggested that you use a more advanced text editor that handles formatting more effectively. One such text editor (that is free) is [http://notepad-plus-plus.org/ NotePad++], which includes a number of options for easy-to-read and easy-to-write code. Creating a lua file in this manner is as simple as renaming the file with a .lua extension (rather than .txt, for example): NotePad++ itself can save its text files as lua scripts.
  
 
Whenever example code is used in this tutorial, it will be displayed using a special formatting, as shown below:
 
Whenever example code is used in this tutorial, it will be displayed using a special formatting, as shown below:
Line 8: Line 9:
 
This is an example sentence.
 
This is an example sentence.
 
All spaces/symbols are shown completely          like so.
 
All spaces/symbols are shown completely          like so.
−
In addition, html formatting <b>cannot work</b> here.
+
In addition, html formatting <b>cannot</b> work here.
 
However, certain words (for in or and, etc) as well as formats are colored;
 
However, certain words (for in or and, etc) as well as formats are colored;
 
--comments in the language are given using two dashes;
 
--comments in the language are given using two dashes;
Line 16: Line 17:
 
Much of the tutorial is written in this format, as it is far easier to diplay lua without the default formatting of Wikimedia getting in the way.
 
Much of the tutorial is written in this format, as it is far easier to diplay lua without the default formatting of Wikimedia getting in the way.
  
−
==Basic Syntax and Definitions==
+
'''Current tutorials:''' (these have yet to be updated for v0.9.9.5)
  
−
The following is a very quick explanation of general programming lua syntax. If you know even a little about programming, you do not likely need to read any of this.
+
*[[Modding:Tutorial/Basic Syntax and Definitions|Basic Syntax and Definitions]]
−
 
+
*Customization
−
Writing in a computer language is very brief and exact, and never involves any connotations or implications. In fact, with the exception of particular inputs and outputs, much of the language is entirely internal, purposed to communicate with the computer in order to perform calculations. The basis of these calculations rests on binary relations: true (1) and false (0). If you have a routine that should only be performed until certain conditions, for example, you will want to use binary relations to determine whether or not the routine is run.
+
**[[Modding:Tutorial/Game Objects|Game Objects]]
−
 
+
**[[Modding:Tutorial/Custom Items|Custom Items]]
−
The most basic relations are simple comparisons with numbers.
+
**[[Modding:Tutorial/Custom Beings|Custom Beings]]
−
 
+
**[[Modding:Tutorial/Designing AI|Designing AI]] (incomplete)
−
<source lang="lua">
+
−
3 == 3  --true (note that equality relations are understood with ==)
+
−
12 == 1 --false
+
−
6 >= 2  --true
+
−
6 <= 2  --false
+
−
</source>
+
−
 
+
−
Rather than directly using numbers, you will likely want to assign them to a variable. In lua, declaring a variable can be done by preceding it with the word "local", and assigning the variable a value is done using the equal sign.
+
−
 
+
−
<source lang="lua">
+
−
local yes = 1
+
−
local no = 0
+
−
</source>
+
−
 
+
−
With this code, whenever you would use the variable 'yes', it will be read as a true value, and whenever you would use the variable 'no', it will be read as a false value. (Note that the parameters are not always "local": this will be covered more in detail later.) Variables can be reassigned as much as you want unless they are read-only (this comes up in a few places).
+
−
 
+
−
A value's type, or class, is usually determined by the API: that is, the values you can assign when modifying DoomRL content usually have to be a particular class, or else they won't work. When a variable needs to be a word or some amount of characters, it is called a string and should be placed in single- or double-quotes. Boolean values can be written either as true/false or as 1/0 (respectively); integers must be a whole number; bytes must be written as an integer between 0 and 15. Internally, you will tend to deal with booleans, integers, and strings exclusively, unless you create your own class.
+
−
 
+
−
Trying to determine how your code will run is done through conditional statements. These include:
+
−
 
+
−
<source lang="lua">
+
−
if condition1      --check to see if condition1 is true
+
−
    then result1    --if condition1 was true, do result1
+
−
elseif condition2  --if condition1 was false, check to see if condition2 is true
+
−
    then result2    --if condition2 was true, do result2
+
−
else
+
−
    result3        --if condition2 was false, do result3
+
−
end                --conditional statements must always finish with this line
+
−
</source>
+
−
 
+
−
==Tables==
+
−
 
+
−
A very large part of customizing the objects in DoomRL (weapons, powerups, enemies, etc) has to do with creating, manipulating, and referencing lua tables. All objects in the game are associated with a particular table. The following is an example of a very simple table:
+
−
 
+
−
<source lang="lua">
+
−
Dude = {
+
−
    name = 'Game Hunter'
+
−
    type = 'DRL player'
+
−
}
+
−
</source>
+
−
 
+
−
Adding this to a lua script would create a table called "Dude" with two variables: name, which is set to the value 'Game Hunter'; and type, which is set to the value 'DRL player'. Often variables within tables are called properties, since they are a part of the table and hence a property (e.g., all matter has some amount of mass, therefore mass is a property of matter).
+
−
 
+
−
While you can create tables yourself, more often than not you will be creating tables based on a specific class. These classes are based on the game's core objects and include "Beings", "Items", and "Missiles". To create a table using a class, do not use an equal sign.
+
−
 
+
−
<source lang="lua">
+
−
Beings{
+
−
    id = "enemy"
+
−
    ....
+
−
}
+
−
</source>
+
  
−
The result is that a new table called "enemy" will exist as a part of the Beings class.
+
*Example Modules: Singular
 +
**[[Modding:Tutorial/Constructing a Map|Constructing a Map]] (the basics)
 +
**[[Modding:Tutorial/Recreating Hell's Arena|Recreating Hell's Arena]]
 +
**[[Modding:Tutorial/The Infinite Arena|The Infinite Arena]]
 +
*Example Modules: Episodic
 +
**[[Modding:Tutorial/Building an Episode|Building an Episode]] (the basics)

Latest revision as of 04:24, 25 January 2012

Welcome to the DoomRL modules tutorial. The objective of this guide is to explain how to develop your own modules for DoomRL as easily and as accurately as possible: therefore, its scope is fairly limited and will only cover basic techniques in customizing objects, maps, and game events. However, it is written at the level of one who has little to no background knowledge of programming languages, and so is ideal for a player who doesn't understand the fundamentals of scripting. Anyone who has the ambition to create a unique and enjoyable game out of the DoomRL engine should use this as a tool to get started.

Modifying DoomRL content is done through lua, a scripting language designed to communicate with a variety of other computer languages. (You can find out more about lua by following this link.) As such, a great deal of what can be done for the purpose of DoomRL modding is handled by the API, or application programming interface, which allows a modder to issue commands that are sent to the DoomRL engine (written in Pascal). The formatting and syntax is relatively simple and flexible, so there are a number of ways to write code in lua that will produce the same outcome. We will use a particular format, although alternatives will be explained as they come up.

Writing lua code yourself is done in a text editor. What text editor you use depends on your operating system: for Windows, it is Notepad. It is suggested that you use a more advanced text editor that handles formatting more effectively. One such text editor (that is free) is NotePad++, which includes a number of options for easy-to-read and easy-to-write code. Creating a lua file in this manner is as simple as renaming the file with a .lua extension (rather than .txt, for example): NotePad++ itself can save its text files as lua scripts.

Whenever example code is used in this tutorial, it will be displayed using a special formatting, as shown below: 

This is an example sentence.
All spaces/symbols are shown completely          like so.
In addition, html formatting <b>cannot</b> work here.
However, certain words (for in or and, etc) as well as formats are colored;
--comments in the language are given using two dashes;
'and strings are expressed' between "single or double quotes".

Much of the tutorial is written in this format, as it is far easier to diplay lua without the default formatting of Wikimedia getting in the way.

Current tutorials: (these have yet to be updated for v0.9.9.5)

Retrieved from "https://drl.chaosforge.org/w/index.php?title=Modding:Tutorial&oldid=1667"
Personal tools