FAQ • Search • Login
View unanswered posts | View active topics It is currently Sun Dec 01, 2024 3:54 am

Board index » Cortex Command » Mod Making » Lua Scripting

All times are UTC [ DST ]



Reply to topic  Page 1 of 3
  [ 44 posts ]  Go to page 1, 2, 3  Next
Print view Previous topic | Next topic 
 Cortex Command Lua Scripting Tutorial 
Author Message
CaveCricket48
User avatar

Joined: Tue Jun 12, 2007 11:52 pm
Posts: 13144
Location: Here
Reply with quote
Post Cortex Command Lua Scripting Tutorial
I wipped up a Lua scripting tutorial for CC to help those who do not know Lua/have limited knowledge. To the Lua pros, if you find any mistakes in the tut, feel free to point them out.

Downloadable text file version here:

Attachment:
CC Lua Tut.txt [17.89 KiB]
Downloaded 2108 times

Be sure to turn "Word Wrap" on in the "Format" button in Notepad if you're viewing it.

Change Log:
8-29-2010:
-Small typo fix
-Added missile example

4-27-2010:
-Small typo fix

3-14-2010:
-Small typo fix

3-5-2010:
-Small typo fix

2-27-2010:
-Put in pointers to devices and particles

2-26-2010:
-Initial Release


---- Start Tutorial ----

Contents:

1.0 - Starting Off
-> 1.1 Making a Lua file
-> 1.2 Attaching a script to an object

2.0 - Lua scripting basics
-> 2.1 Comments
-> 2.2 Data types
-> 2.3 Variables
-> 2.4 Statements
-> 2.5 Tables
-> 2.6 For loop

3.0 - Cortex Command Lua stuff
-> 3.1 Script phases
-> 3.2 Self variable
-> 3.3 Functions
-> 3.4 Pointers

4.0 - Functions and properties in the wiki

5.0 - Example scripts
-> 5.5 Mine
-> 5.2 Missile


________________________

----- 1.0 - Starting Off -----
________________________


In Cortex Command, Lua allows objects to do things that they normally wouldn't be able to do or to create special effects.



- 1.1 Making a Lua file -

The way Lua scripts work in Cortex Command is that scripts are attached to objects created with ini coding. To make a Lua file with plain Notepad on windows, just make a new text file, go to "File", "Save As...", change "Save as type:" to all files, and change the ".txt" extension of the file name to ".lua". If there is no extension, just add ".lua" to the end of the file name. Then press "Save" and you've made a Lua file.



- 1.2 Attaching a script to an object -

To attach a Lua script to an "ini" coded object, simply put "ScriptPath = <filepath to Lua file>" in the object's code block with appropriate tabbing.




________________________

----- 2.0 - Lua scripting basics -----
________________________


--- 2.1 Comments ---

Comments in Lua scripting are lines of text that are not read by the game/program, and are mostly used to annotate the script. To annotate, make 2 hyphens and anything after them on the same line is a comment.

Code:
-- This is a comment




--- 2.2 Data types ---

Data types are types of data that are used for variables and properties. There are 5 main ones in CC: numerical (numbers), text, boolean, Vector, and nil. The first 2 are self-explanitory. A boolean is (true) or (false). A Vector in CC is a coordinate (X,Y). numerical data is used by just typing numbers. Test is used by having a pair of quotation marks (") with text in-between them. A vector is used by having the word "Vector" followed by 2 numbers seperated by a comma in a pair of parenthesis. Nil is nothing (not to be confused with the number zero).

Code:
1234

"text"

true
false

Vector(1,1)
Vector(5,2)
Vector(-7,6)

nil




--- 2.3 Variables ---

Variables are things in Lua that you can give a value to. They are used for storing information so you can recall it later. A variable consists of its name, a single equal sign, and a value.

Code:
X = 5


To change a variable, simply type the same thing again with a new value:

Code:
X = 2


You can also make a variable have the same value as another variable by setting its value to the other variable's name:

Code:
A = 5
X = A


That would make variable "X" equal to 5.




There are 2 types of variables in CC: global and local. Global variables can be changed by any object's script re-stating the value and only one variable with that name can exist. Global variables look like the ones above in the examples.

Local variables are variables that can have multiple copies, each tied to the object with the script that created them. To make a local variable, type "local" before the variable name followed by a space. Setting a local variable to another local variable works in a similar way as global variables.

Code:
local varA = 5
local varB = varA


This would make variable "varB" equal to 5. Note how the word "local" was not used after the (=) when recalling the variable "varA".

Another useful thing about variables is that you can use variables to set a certain property to an object, and store an object to a variable. When storing an object to a variable, it is easier to interact with and is called a pointer. To use to variables to change the property of an object, you'll need the variable that is a defined pointer to the object (we'll get to this later), followed by a period, the property name, and equal sign, and value.

Code:
thing.GetsHitByMOs = false


"thing" is a pointer to the object, "GetsHitByMOs" is an ini coded property, and "false" is the value.

A commonly used pointer that is already defined is "self". The pointer always refers to the object that the script is attached to.

Code:
self.GetsHitByMOs = false




--- 2.4 Statements ---

The way Lua works (and programming in general) is by checking statements to see if they are true and doing stuff if so (or if not so). Let's look at the code below.

Code:
if X == 1 then
<do stuff>
end


What this is doing is checking to see if the variable "X" is equal to "1", and will "do stuff" ("<do stuff>" not an actual action, just a place-holder for other things we'll get to later) if the statement is true. Note the "end" at the bottom of the code block, that says that the "<do stuff>" part of that statement is over. If you don't put an "end" after a statement (the end of a statement is after its <do stuff> too) then you will get an error. Also note how there are 2 equal signs in the "if" line. "==" is for checking congruency and "=" is for setting variables/properties. Checking sybmols are:

Code:
-- Is equal to
==

-- Is not equal to
~=

-- Is less than
<

-- Is greater than
>

-- Is less than or equal to
<=

-- Is greater than or equal to
>=


Statements can also have "else" checks inside of them. Else checks do stuff if the main "if" line is not equal to the value that it is checking for.

Code:
if X == 1 then
<do stuff>
else
<do different stuff>
end


Elseif checks are like secondary "if" statements and work in a similar way:

Code:
if X == 1 then
<do stuff>
elseif X == 2 then
<do other stuff>
end


You can have more than one "elseif" check in a statement, but only one "else".



--- 2.5 Tables ---

Lists (also called tables and arrays) are like variables that can have mutiple values. To make a list, make the list name followed by an equal sign and a pair of brackets.

Code:
thelist = {}


Adding a value to a list is similar to making/changing a variable's value. You need to type the list's name followed by a pair of square brackets with the desired list number, and equal sign, and then a value.

Code:
thelist[1] = 1234
thelist[2] = 37065


The number symbol with a list's name in front of it tells the number of items in a list.

Code:
numbercheck = #thelist


If the list is the same list as the one in the above examples, then this would make the variable "numbercheck" equal to 2.

To clear all values from a list, type the list's name followed by an equal sign and an empty pair of brackets. To clear a single value, set the value to nil.

Code:
-- Clearing the whole list
thelist = {}

-- Clearing a single item
thelist[1] = nil


Lists can be global and local like variables.

Code:
thelist = {}
local thesecondlist = {}




--- 2.6 For Loop ---

For Loops are used to do multiple repetitive things in one short chunk of script. "For" loop format below.

for <variable> = <start number>, <number of how many times to do the action> do

An example of a standard "for" statement below.

Code:
for i = 1, 5 do
<do stuff>
end


Let's look at each individual part of this:

for
- The starting keyword

i = 1
- The "i" is a temporary variable that the "for" statement uses to store how many times it did the action (including the one it's on). The "i" can be changed to any name like a variable. The "1" there is where to start the count.

5
- The number of times to "<do stuff>".

To stop a for loop, have "break" inside an "if" statement that checks for the right conditions.

Code:
for i = 1, 5 do
   if i == 3 then
    break
   end
end





________________________

----- 3.0 - Cortex Command Lua stuff -----
________________________


--- 3.1 Script Phases ---

These are technically called "funtions," but that would be confusing, considering what the next topic topic is called. Script phases are parts of the script that are run only when the object has been created, while it exists, or when destroyed. Script phases also require "end"s like if statements.

Code:
-- Anything in between the the "function Create(self) and its end will only run when the object is created. (only happens once)
function Create(self)

end

-- Anything in between the the "function Update(self) and its end will only run when the object is existing.
function Update(self)

end

-- Anything in between the the "function Destroy(self) and its end will only run when the object is destroyed. (only happens once)
function Destroy(self)

end




--- 3.2 "self" variable ---

In Cortex Command Lua, scripts can set a "self" variable when inside a script phase. These variables are pretty much work the same as local variables.
Code:
self.varA = 12
self.varB = self.varA


Note how the "self" bit sticks to the variable name where ever the variable is used.



--- 3.3 Functions ---

Functions are the part of Lua that are pre-set into the game (or program) and interact with stuff. Function format is the funtion's group name followed by colons, the function's name, and its arguments (required data for it to work) seperated by commas in parenthesis. Many Cortex Command function group names can be replaced by a pointer to something that they can interact with. An actual function below:

Code:
anactor:AddImpulseForce(Vector(0,-10),Vector(0,0))


The function information from the Cortex Command Lua wiki:

Code:
AddImpulseForce
Adds impulse force (or instant momentum) to this MovableObject for the next time Update() is called.

Arguments:

 - An Vector with the impulse force vector that will directly be added to this MovableObject's momentum next Update(). In kg * m/s.
 - A Vector with the offset, in METERS, of where the impulse is being applied relative to the center of this MovableObject.

Return value:

None.


"anactor" is a pointer to an actor, "AddImpulseForce" is the name of the function, and the stuff in the parenthesis are data required for the function to work. In the part of the function info that says "Return value" is what the function spits out when it runs. For example, if the retrun function was the target object's mass, then making a variable's value the function would make it the object's mass.

Most functions in Cortex Command can be found in the wiki, so be sure to check it out.



--- 3.4 Pointers ---

Alright, we finally got to pointers!
In Cortex Command, pointers are variables that "store" an object to them. Or you can imagine it as a giant arrow directed towards the object. Whatever property you set on a pointer or use a function on it, will effect the thing that they're "pointing" at.

There are several ways to make pointers. A common one is to use a special "for" statement that goes through a all of the objects of a certain type and have a statement that checks if the object is the one you want. The script chunk below is attached to a object that looks for the actor is named "Dummy" and then sets a pointer to it called "local pointer".

Code:
function Update(self)

for actor in MovableMan.Actors do
   if actor.PresetName == "Dummy" then
    local pointer = actor
    break
   end
end

end


What the above script chunck does is go through all actors in-game untill it finds an actor with "PresetName" as "'Dummy'". Then it sets a pointer to that actor as "local pointer" and stops the "for" statement with "break". The term "actor" is a pointer to an actor, and is transfered to "local pointer" for easier reference.

There are 2 other "for" lines that get pointers on devices and particles.

Code:
-- Pointer to devices
for item in MovableMan.Items do
end


Code:
-- Pointer to particles
for particle in MovableMan.Particles do
end





________________________

----- 4.0 - Functions and properties in the wiki -----
________________________

This is a link to a section of the Cortex Command wiki that contains documentation for many functions and properties.
http://wiki.datarealms.com/wiki/index.php/LuaDocs/Index




________________________

----- 5.0 - Example scripts -----
________________________


Below are some examples of complete scripts with comments that may help for reference.


--- 5.1 Mine ---
This script is for a basic mine that explodes when actors get within a specific distance of the scripted object.

With comments:
Code:
-- While the object is existing...
function Update(self)

-- Go through all actors.
   for actor in MovableMan.Actors do

-- Uses a function plus a vector property to store the distance between the actor and scripted object in a variable.
      local distcheck = SceneMan:shortestDistance(self.Pos,actor.Pos,true).Magnitude

-- Statement checking if the distance check (variable "local distcheck") is less than 30. If so, then do the action...
      if distcheck < 30 then

-- GibThis() is a function that makes the targeted object gib. Since the target is "self" then the scripted object gibs.
         self:GibThis()

-- Stop the for loop.
         break

-- End of the "if" statement.
      end

-- End of the "for" statement.
   end

-- End of the "function Update(self)".
end

Without comments:
Code:
function Update(self)
   for actor in MovableMan.Actors do
      local distcheck = SceneMan:shortestDistance(self.Pos,actor.Pos,true).Magnitude
      if distcheck < 30 then
         self:GibThis()
         break
      end
   end
end




--- 5.2 Missile ---
A script designed to be attched to a "rocket" emitter shot from a gun. The script searches for actors of the enemy team and rotates the emitter to the direction of the closest one.

With comments:
Code:
-- When the object is created...
function Create(self)

-- Go through all actors in-game...
   for actor in MovableMan.Actors do

-- Check if the actor has the object named "Missile Launcher" and check the distance between the missile and the actor. If so...
      if actor:HasObject("Missile Launcher") and SceneMan:ShortestDistance(self.Pos,actor.Pos,true).Magnitude < 50 then

-- Set the team that the missile doesn't want to lock onto into a variable
         self.ignoreteam = actor.Team

-- Stop the "for" loop.
         break

-- End of the "if" statement.
      end

-- End of the "for" loop.
   end

-- End of "function Create(self)".
end

-- While the object is existing...
function Update(self)

-- Check if the variable "self.target" is a pointer to a living actor.
   if MovableMan:IsActor(self.target) then

-- Set the scripted object's rotation pointing at the "self.target" actor.
      self.RotAngle = SceneMan:ShortestDistance(self.Pos,self.target.Pos,true).AbsRadAngle

-- Enable the scripted object's emission (the scripted object needs to be an emitter)
      self:EnableEmission()

-- If the variable "self.target" is NOT a pointer to a living actor, then...
   else

-- Create a variable that keeps track of the shortest distance between the probable target and the missile so far. Let's leave it at "-1" so we know it hasn't been used yet.
      self.shortestdistance = -1

-- Go through all of the actors in-game.
      for actor in MovableMan.Actors do

-- If the actor is on the enemy team...
         if actor.Team ~= self.ignoreteam then

-- Store a distance check of the scripted object and actor into a variable.
            self.curdist = SceneMan:ShortestDistance(self.Pos,actor.Pos,true).Magnitude

-- Make sure the distance is no greater than 500. Then check if either the "self.shortestdistance" has been unused in order to continue, or if the "self.shortestdistance" has been used and the distance is less then the value of "self.shortestdistance".
            if self.curdist < 500 and (self.shortestdistance == -1 or self.shortestdistance ~= -1 and self.curdist < self.shortestdistance) then

-- If everything checks out okay, make this actor the "self.target" and store the distance between them for later use.
               self.target = actor
               self.shortestdistance = self.curdist

-- End of the "if" statement.
            end

-- End of the "if" statement.
         end

-- End of the "for" loop.
      end

-- End of the "if" statement.
   end

-- End of "function Update(self)"
end

Without comments:
Code:

function Create(self)

   for actor in MovableMan.Actors do
      if actor:HasObject("Missile Launcher") and SceneMan:ShortestDistance(self.Pos,actor.Pos,true).Magnitude < 50 then
         self.ignoreteam = actor.Team
         break
      end
   end
end

function Update(self)

   if MovableMan:IsActor(self.target) then
      self.RotAngle = SceneMan:ShortestDistance(self.Pos,self.target.Pos,true).AbsRadAngle
      self:EnableEmission()
   else
      self.shortestdistance = -1
      for actor in MovableMan.Actors do
         if actor.Team ~= self.ignoreteam then
            self.curdist = SceneMan:ShortestDistance(self.Pos,actor.Pos,true).Magnitude
            if self.curdist < 500 and (self.shortestdistance == -1 or self.shortestdistance ~= -1 and self.curdist < self.shortestdistance) then
               self.target = actor
               self.shortestdistance = self.curdist
            end
         end
      end
   end

end


Last edited by CaveCricket48 on Sun Aug 29, 2010 5:26 pm, edited 6 times in total.
Sat Feb 27, 2010 4:15 am
Profile
Mind
User avatar

Joined: Thu Mar 06, 2008 10:54 pm
Posts: 1360
Location: USA
Reply with quote
Post Re: Cortex Command Lua Scripting Tutorial
Sweet
Sat Feb 27, 2010 4:40 am
Profile
dragonxp
User avatar

Joined: Wed Sep 09, 2009 3:16 am
Posts: 3032
Location: Somewhere in the universe
Reply with quote
Post Re: Cortex Command Lua Scripting Tutorial
This is something i need.
Sat Feb 27, 2010 4:51 am
Profile
CaveCricket48
User avatar

Joined: Tue Jun 12, 2007 11:52 pm
Posts: 13144
Location: Here
Reply with quote
Post Re: Cortex Command Lua Scripting Tutorial
Forgot to put in pointers to devices and particles, now they're in there.
Sat Feb 27, 2010 6:08 pm
Profile
Geti
User avatar

Joined: Sun Jul 13, 2008 9:57 am
Posts: 4886
Location: some compy
Reply with quote
Post Re: Cortex Command Lua Scripting Tutorial
dude, notepad with wordwrap makes copypasting do what it did to the OP. cleaning of the extra returns could be a good idea. very nice tutorial though.
Thu Mar 04, 2010 11:36 am
Profile WWW
Grif
REAL AMERICAN HERO
User avatar

Joined: Sat Jan 27, 2007 10:25 pm
Posts: 5655
Reply with quote
Post Re: Cortex Command Lua Scripting Tutorial
notepad++ forever

lua
syntax
highlighting
and
function
collapsing
Thu Mar 04, 2010 4:13 pm
Profile
Geti
User avatar

Joined: Sun Jul 13, 2008 9:57 am
Posts: 4886
Location: some compy
Reply with quote
Post Re: Cortex Command Lua Scripting Tutorial
amen to that and not having to tap tab 7-8 times for each new line in an involved function.
also some links to pil and such could also be good in the OP.
Thu Mar 04, 2010 8:10 pm
Profile WWW
The Man

Joined: Wed Mar 03, 2010 12:28 pm
Posts: 20
Reply with quote
Post Re: Cortex Command Lua Scripting Tutorial
gvim forever

gvim+molokai

ughghnnn yesssnnnnn
Sat Mar 06, 2010 7:56 pm
Profile
Mind
User avatar

Joined: Thu Mar 06, 2008 10:54 pm
Posts: 1360
Location: USA
Reply with quote
Post Re: Cortex Command Lua Scripting Tutorial
Oh yeah. NP++
A++
++
Sun Mar 07, 2010 12:54 am
Profile
LowestFormOfWit
User avatar

Joined: Mon Oct 06, 2008 2:04 am
Posts: 1559
Reply with quote
Post Re: Cortex Command Lua Scripting Tutorial
Minor correction under section 3.1: The example for function Destroy(self) reads function Create(self).

Also, incredible. I might actually start this up now.
Fri Mar 12, 2010 7:36 am
Profile
Awesomeness
User avatar

Joined: Sat Jun 19, 2010 5:02 pm
Posts: 331
Location: Mekkan
Reply with quote
Post Re: Cortex Command Lua Scripting Tutorial
I already understand how to use Lua, but how do I integrate this into a mod? As in, for example, I have a mod of only .ini's. (based off of http://www.moddb.com/mods/the-crowguard/tutorials/creating-your-first-cc-modification) I can't seem to find what the bullets it shoots are called, but if I could find their name, I'd be able to make a Lua script that would make the bullets emit fire in random directions during the update method. But how do I tell the .ini's to use the Lua script in the first place?
Sun Jun 20, 2010 1:52 pm
Profile
Petethegoat
User avatar

Joined: Mon Jun 15, 2009 4:02 pm
Posts: 905
Reply with quote
Post Re: Cortex Command Lua Scripting Tutorial
ScriptPath = YourMod.rte/Lua.lua
Sun Jun 20, 2010 1:55 pm
Profile WWW
CaveCricket48
User avatar

Joined: Tue Jun 12, 2007 11:52 pm
Posts: 13144
Location: Here
Reply with quote
Post Re: Cortex Command Lua Scripting Tutorial
CaveCricket48 wrote:
- 1.2 Attaching a script to an object -

To attach a Lua script to an "ini" coded object, simply put "ScriptPath = <filepath to Lua file>" in the object's code block with appropriate tabbing.

It was also in the very begining of the tutorial.
Sun Jun 20, 2010 3:47 pm
Profile
f4nt4sy

Joined: Sun May 16, 2010 10:37 am
Posts: 23
Reply with quote
Post Re: Cortex Command Lua Scripting Tutorial
Quote:
Below are some examples of complete scripts with comments that may help for reference.


I need more Examples! Please, iam starving for that! I cant learn a thing without examples... Would be so great. Like, hum.

Kill "xy" then distplay "victory"

or

gather "xy" funds then spawn ai controlled dropship

and stuff like that. would be a sooooooo bigbig help for me iam gettin nowhere with raw info, i need something to analyze. Maybe not every kind of combination but could you give some examples how luacommands interact with each other and the mainframe of a luascript and so on.

thanks for your work so far anyways!
Mon Jul 19, 2010 11:12 pm
Profile
Darkdoom
User avatar

Joined: Mon Jun 28, 2010 10:06 pm
Posts: 461
Location: STEPPING INTO THE RING
Reply with quote
Post Re: Cortex Command Lua Scripting Tutorial
awsome Tut. I now mave enough confidence to attempt some Lua.

(Notepad++ forever, and ever, and ever, and ever, and ever,)
Mon Jul 26, 2010 9:58 pm
Profile
Display posts from previous:  Sort by  
Reply to topic   Page 1 of 3
  [ 44 posts ]  Go to page 1, 2, 3  Next

Board index » Cortex Command » Mod Making » Lua Scripting

All times are UTC [ DST ]

Who is online

Users browsing this forum: No registered users

You cannot post new topics in this forum
You cannot reply to topics in this forum
You cannot edit your posts in this forum
You cannot delete your posts in this forum
You cannot post attachments in this forum

Search for:
Jump to:  
Powered by phpBB © 2000, 2002, 2005, 2007 phpBB Group.
Designed by STSoftware for PTF.
[ Time : 0.083s | 15 Queries | GZIP : Off ]