PRG at 22:06, 9 December 2024

2024-12-09T22:06:27Z

← Older revision		Revision as of 00:06, 10 December 2024
Line 1:		Line 1:
	{{CatUp\|Lua Help}}		{{CatUp\|Lua Help}}

	So, you want to learn how to script? This should be the very first place to look. Be sure to read everything carefully, making sure that you understand what is being read. If you have any questions or comments feel free to ask them either [[Talk:Scripting\|on the discussion page]] or on the [http://~~www~~.~~roblox.com~~/Forum Forum].		So, you want to learn how to script? This should be the very first place to look. Be sure to read everything carefully, making sure that you understand what is being read. If you have any questions or comments feel free to ask them either [[Talk:Scripting\|on the discussion page]] or on the [http://cirkl.zone/Forum/Default.aspx Forum].

	==Introduction==		==Introduction==

PRG: Created page with "{{CatUp|Lua Help}} So, you want to learn how to script? This should be the very first place to look. Be sure to read everything carefully, making sure that you understand what is being read. If you have any questions or comments feel free to ask them either on the discussion page or on the [http://www.roblox.com/Forum Forum]. ==Introduction== The ROBLOX scripting language is [http://www.lua.org Lua 5.1], a concise and efficient scripting language us..."

2024-12-09T22:04:54Z

Created page with "{{CatUp|Lua Help}} So, you want to learn how to script? This should be the very first place to look. Be sure to read everything carefully, making sure that you understand what is being read. If you have any questions or comments feel free to ask them either on the discussion page or on the [http://www.roblox.com/Forum Forum]. ==Introduction== The ROBLOX scripting language is [http://www.lua.org Lua 5.1], a concise and efficient scripting language us..."

New page

{{CatUp|Lua Help}}

So, you want to learn how to script? This should be the very first place to look. Be sure to read everything carefully, making sure that you understand what is being read. If you have any questions or comments feel free to ask them either [[Talk:Scripting|on the discussion page]] or on the [http://www.roblox.com/Forum Forum].

==Introduction==

The ROBLOX scripting language is [http://www.lua.org Lua 5.1], a concise and efficient scripting language used in games and embedded systems. Documentation on the language can be found at [http://www.lua.org/docs.html here].

Scripting requires the [[Script]] object which can control a number of things. For list of Lua objects that can be used, see the [[Class Reference]].

This article is documentation for people slightly familiar with the language. If you have no idea what you're doing, you may want to look at these:

*[[Absolute beginner's guide to scripting]]
*[[Flowcharts]]
*[[Reusing code]]

[[Intro to Scripting: Make a Dance Floor]] is a tutorial for beginners that shows how [[Script|scripts]] can be used to control the [[BrickColor (Property)|color]] of [[Part|parts]]. Also, when scripting it is also important to look at the [[Object Browser]]. Keep it open when you're making scripts in [[Edit|Edit mode]]. It can show where and why you've made a mistake.

==Fundamentals==

These are the basics. It is very important to understand these.

===Defining Scripts===

Script objects can be placed under the [[RBX.lua.Workspace (Service)|Workspace]] or under [[Part|parts]], [[Model|models]], [[RBX.lua.StringValue (Object)|values]], etc.

Scripts can also be written and executed in the Command toolbar. To execute a script from the command bar:

#Edit a place in [[Roblox Studio|ROBLOX Studio]]. 
#Select View-->Toolbars-->Command from the menu bar.
#:''The Command toolbar will appear at the bottom of the screen.'' 
#Select View-->[[Output]] from the menu bar.
#:''The Output panel will appear just above the Command toolbar.'' 
#In the Command toolbar's textbox type the following:
#:<pre>print("Hello World")</pre>
#Press the 'Enter' key.
#:''The text "Hello World" appears in the [[Output|Output window]]''

===Script Execution===

Script objects only run under certain conditions:

* Scripts entered in the Command toolbar execute when you press Enter. This only applies if you're in either edit mode or [[Solo mode]].

* Scripts will run, as said before, if under the [[RBX.lua.Workspace (Service)|Workspace]] or general containers.

* Scripts inside a Tool run when the Tool is activated.

Also, if you want a script to NOT run when the game is started, make sure that under the [[Properties]] for a script, the [[Bool]] 'Disabled', is set to true. A script will also not run if under the [[Lighting]], [[Sound Service]], or any [[Service]] besides the [[RBX.lua.Workspace (Service)|Workspace]]. If the script's [[Parent (Property)|property]] is under the [[DataModel]], then it will also not run.

===Environments and Libraries===

Each Script has its own copy of the global [http://www.lua.org/manual/5.1/manual.html#2.9 Environment]. This "sandboxes" each script. For instance another script cannot overwrite the global data defined in another script.

ROBLOX loads the following Lua standard libraries: [http://www.lua.org/manual/5.1/manual.html#5.1 Basic Functions], [http://www.lua.org/manual/5.1/manual.html#5.2 Coroutine Manipulation], [http://www.lua.org/manual/5.1/manual.html#5.4 String Manipulation], [http://www.lua.org/manual/5.1/manual.html#5.5 Table Manipulation], [http://www.lua.org/manual/5.1/manual.html#5.6 Mathematical Functions]. For security purposes some functions have been removed to deny access to system resources. A list of these functions can be found in the [[Function Dump]] page of the wiki. In addition, some [http://wiki.roblox.com/index.php?title=Category:ROBLOX_Lua_Objects Roblox Lua Objects] have been removed for the very same reason.

===Math===

One important feature that nearly all programming languages use is math. Here's what you need to know:

*You can use the [[Output]] to view your solutions. You can use other types of output too, like [[RBX.lua.Message (Object)|messages]] and [[RBX.lua.Hint (Object)|hints]].
*Roblox can perform complex probelms for you.
*This can make things extremely simple.

Here's a sample of basic math. Open up [[Roblox Studio]], goto File> New, insert a [[Script]] into the [[RBX.lua.Workspace (Service)|Workspace]], make sure that the [[Output]] is open.

{{Example|
<pre>
a = 1 + 1 --'a' represents your math problem.
print(a) --This prints the result.
</pre>
<pre>
a = 5*5+1
print(a)
</pre>
<pre>
a = (9*9) + 19
print(a)
</pre>
}}

For more information, and usage, read the following articles:

*[[Basic math]]
*[[Variables]]
*[[Conditional statements]]
*[[Random numbers]]
*[[How To Increase and Decrease Vector3 Values]]

==Data Model==
The [[DataModel]] is what you would define as 'game' in your scripts. 

Here are Lua 'types' that can be used in a script

===Basic Types===

ROBLOX scripts use the basic [http://www.lua.org/manual/5.1/manual.html#2.2 Lua types] ''[[nil]], [[Bool|boolean]], number, [[string]], function, userdata, [[thread]], and [[Tables|table]]''. In addition, there are the following additional basic types:

====Vector3====

[[Vector3]] represents a 3D vector. All [[properties]] are [[Read-Only]].
{| border="1"
! Property !! Type !! Description
|-
| <code>x</code> || number ||| the x-coordinate
|-
| <code>y</code> || number ||| the y-coordinate
|-
| <code>z</code> || number ||| the z-coordinate
|-
| <code>unit</code> || Vector3 ||| a normalized copy of the vector
|-
| <code>magnitude</code>|| number ||| the length of the vector
|}

{| border="1"
! Member Function !! Description
|-
| <code>Vector3 lerp(Vector3 goal, number alpha)</code> || returns a Vector3 lerped between this Vector3 and the goal. alpha should be between 0 and 1
|}

====CFrame====

[[CFrame]], know as character frame, but more specifically coordinate frame.

{| border="1"
! Constructor !! Description
|-
| <code>new()</code> || Creates an identity CFrame
|-
| <code>new(v)</code> || Creates CFrame from offset Vector3 v
|-
| <code>new(v, l)</code> || Creates CFrame from offset Vector3 v looking at point l
|-
| <code>new(x, y, z)</code> || Creates CFrame from offset (x, y, z)
|-
| <code>new(x, y, z, qx, qy, qz, qw)</code> || Creates CFrame from offset (x, y, z) and quaternion (qx, qy, qz, qw)
|-
| <code>new(x, y, z, R00, R01, R02, R10, R11, R12, R20, R21, R22)</code> || Creates CFrame from offset (x, y, z) and rotation matrix (R00, R01, R02, R10, R11, R12, R20, R21, R22)
|-
| <code>fromEulerAnglesXYZ(x, y, z)</code> || Creates a rotated CFrame (x, y, z) in radians
|-
| <code>fromAxisAngle(v, r)</code> || Creates a rotated CFrame from a unit vector and a rotation in [http://en.wikipedia.org/wiki/Radian radians]
|}

{| border="1"
! Property !! Type !! Description
|-
| <code>p</code> || Vector3 ||| the translation
|-
| <code>x</code> || number ||| the x-component of translation
|-
| <code>y</code> || number ||| the y-component of translation
|-
| <code>z</code> || number ||| the z-component of translation
|-
| <code>lookVector</code> || Vector3 ||| returns the facing direction along each axis
|}

{| border="1"
! Member Function !! Description
|-
| <code>CFrame inverse()</code> || returns the inverse of this CFrame
|-
| <code>CFrame toWorldSpace(CFrame)</code> || returns a CFrame transformed from Object to World coordinates. Also works with tuples
|-
| <code>CFrame toObjectSpace(CFrame)</code> || returns a CFrame transformed from World to Object coordinates. Also works with tuples
|-
| <code>Vector3 pointToWorldSpace(Vector3)</code> || returns a Vector3 transformed from Object to World coordinates. Also works with tuples
|-
| <code>Vector3 pointToObjectSpace(Vector3)</code> || returns a Vector3 transformed from World to Object coordinates. Also works with tuples
|-
| <code>Vector3 vectorToWorldSpace(Vector3)</code> || returns a Vector3 rotated from Object to World coordinates. Also works with tuples
|-
| <code>Vector3 vectorToObjectSpace(Vector3)</code> || returns a Vector3 rotated from World to Object coordinates. Also works with tuples
|}

{| border="1"
! Operator !! Description
|-
| <code>CFrame * CFrame</code> || returns composition of two CFrames
|-
| <code>CFrame * Vector3</code> || returns Vector3 transformed from Object to World coordinates
|-
| <code>CFrame + Vector3</code> || returns CFrame translated by Vector3
|-
| <code>CFrame - Vector3</code> || returns CFrame translated by -Vector3
|}

====Color3====

[[Color3]], sets color likely in [http://en.wikipedia.org/wiki/Hexadecimal Hex] format (e.g. 1, 255, 98).

====BrickColor====

{| border="1"
! Function!! Type !! Description
|-
| <code>new</code> || BrickColor ||| returns a BrickColor (from a number, string, Color3 or r-g-b values)
|-
| <code>Random</code> || BrickColor ||| returns a random BrickColor
|-
| <code>White</code> || BrickColor ||| returns White
|-
| <code>Gray</code> || BrickColor ||| returns Gray
|-
| <code>DarkGray</code> || BrickColor ||| returns Dark Gray
|-
| <code>Black</code> || BrickColor ||| returns Black
|-
| <code>Red</code> || BrickColor ||| returns Red
|-
| <code>Yellow</code> || BrickColor ||| returns Yellow
|-
| <code>Green</code> || BrickColor ||| returns Green
|-
| <code>Blue</code> || BrickColor ||| returns Blue
|-
|}

{| border="1"
! Property !! Type !! Description
|-
| <code>Number</code> || number ||| The unique number that identifies the BrickColor
|-
| <code>Name</code> || string ||| the name associated with the BrickColor
|-
| <code>Color</code> || Color3 ||| the Color3 associated with the BrickColor
|-
| <code>r</code> || number ||| the red component (between 0 and 1)
|-
| <code>g</code> || number ||| the green component (between 0 and 1)
|-
| <code>b</code> || number ||| the blue component (between 0 and 1)
|}

 Example: 
<code>
local b = BrickColor.Yellow()
 print(b.r)</code> 
prints: 0.96078437566757

'''BrickColor Codes'''

[[image:RobloxColors.PNG]]
[+] Use SirGelatina's [[Color Reference]]

{{Example|1=
<pre>
-- Set myPart color to red.
myPart.BrickColor = BrickColor.new(21)

-- Note that this is equivalent to:
myPart.Color = Color.new(1,0,0)

-- Which is also equivalent to:
myPart.BrickColor = BrickColor.new("Bright red")

-- But only certain colors can be used like this:
myPart.BrickColor = BrickColor.Red()
</pre>
}}

====Connection====
Represents a connection to an [[#Events|Event]]
;

===Globals===
In addition to loading several [[Environments and Libraries|Standard Libraries]] ROBLOX defines the following global variables:

* '''<code>game</code>''' is the DataModel object that is the root of the tree for a Place.
* '''<code>workspace</code>''' is the Workspace object that is a child of the DataModel.
* '''<code>script</code>''' is the Script object that defines the script. (not applicable for the Command toolbar)
* '''<code>print()</code>''' echoes each argument to the Output panel.
* '''<code>time()</code>''' returns returns the current game time in seconds. (NOTE: THis function is scheduled for an upcoming release)
* '''<code>wait(t)</code>''' yields the current thread after "t" seconds have elapsed. If t is not specified, then it yields for a very short period of time. The function returns 2 values: The elapsed time and the current game time.
* '''<code>delay(t,f)</code>''' executes function "f" after "t" seconds have elapse. The function "f" is called with 2 arguments: The elapsed time and the current game time.

===Roblox Objects===
See Main List: [http://wiki.roblox.com/index.php?title=Category:ROBLOX_Lua_Objects RBX.lua Objects]

Each object in the [[Explorer]] is accessible with scripting. ROBLOX Objects have [[Properties]], [[Functions]] and [[Scripting#Events|Events]]. You can browse the member definitions by clicking [[Class Explorer]] under the Help menu.

====Properties====
Object properties are accessed with the “dot” notation:

<pre>script.Name = "Hello"
print(script.Name)</pre>

Some properties are [[Read-Only]]. Attempting to assign to a read-only property will throw an [http://www.lua.org/manual/5.1/manual.html#pdf-error error].

====Functions====
Member functions are called using the [http://www.lua.org/manual/5.1/manual.html#2.5.9| "colon" operator]:

<pre>copy = script:clone()
print(copy.Name)</pre>

Functions in Lua are first-class objects. Therefore you can reference a member function as follows:

<pre>f = script.clone
copy = f(script)
print(copy.Name)</pre>

<div style="border: solid #aaa 1px; background: #f9f9f9; padding: 4px; text-align: left;">
'''Note:''' If you are used to other scripting languages you will need remember to use <code>:</code> instead of <code>.</code> when invoking a member function. <code>script.clone()</code> will not behave as you might expect.</div>

====Events====
Events are fired by Objects. Scripts define code to be executed when an event is fired. Events can optionally send one or more arguments when fired.

There are two ways to handle an Event:

# When a script calls <code>wait()</code>, the currently executing thread yields until the Event is fired. The return values from <code>wait()</code> are the Event arguments. 
# A script calls <code>connect()</code> passing in a function that the Event will call each time the Event is fired. <code>connect()</code> immediately returns a Connection object that can be used to disconnect the listener function.

Here is some sample code:
<pre>
-- Get the Script's Parent object
part = script.Parent

-- Define a handler for the "Touched" Event
function onTouched(otherPart)
print(otherPart.Name .. " touched me!")
end

-- Listen for each time that "part" is touched
connection = part.Touched:connect(onTouched)

-- Put this thread to sleep until a property changes
propName = part.Changed:wait()
print("Property changed: " .. propName)
-- Stop listening to the Touched event
connection:disconnect()</pre>
This code listens for two events: The Part being touched and also for a ''Changed'' event. Since we connected to the Touched event, the function <code/>onTouched()</code> will be called each time Part is touched. However, once the ''Changed'' Event fires and the <code>wait()</code>
call returns, we won't listen for another ''Changed'' event. At that point we also disconnect from the ''Touched'' event.

You are not strictly required to disconnect every connection you make. If the Object owning the Event is collected, then the listening script will no longer get events. Similarly, if the Script Object that owns the listener is removed, then the connection is automatically broken, and any waiting threads can be collected.

== Object Types ==
There are many different object types in Roblox, and in addition to adding them through the Roblox Studio, you can also define a new object in a script with the line Instance.new("className"), with className being the object's type. Following is a listing of many of the various object types.

==Common Mistakes==

The slightest misspelling, or even incorrect capitalization will result in your script failing to work. REMEMBER: Look at the [[Output]] to check for errors. If this doesn't help, back-track and make sure everything is perfect. If you think there is a problem, or you need help in general, report the problem to the [[Bugs]] article, and request help [http://www.roblox.com/Forum on the Forum.] For more help, see the 'See Also' section at the bottom of the page.

==See Also==

In the beginning:...

*[[Your first script]]
*[[Basic Scripting]]
*[[Explaining Scripts]]
*[[Loops]]
*[[How To Increase and Decrease Vector3 Values]]
*[[In-Depth Scripting Guide]]

Scripting [[Tutorials]] and Articles:

*[[Commands]]
*[[Intro to Scripting: Make a Healing Potion]]
*[[In-Depth Scripting Guide]]
*[[Intro to Scripting: Make an Invisibility Tool]]
*[[Teleportation]]
*[[How to make lava]]
*[[How to Make Weapon Giving Teleporters]]
*[[How Do I Make Morphs?]]
*[[How to Create a Black Hole]]
*[[How to Make Conveyor Belts]]
*[[How to Make a Plane]]
*[[How to make circles]]
*[[How to make a spiral staircase]]
*[[How to make a double helix]]

General Information:

*[[Random numbers]]
*[[Commands]]
*[[Conditional statements]]
*[[Variables]]
*[[Flowcharts]]
*[[Generic for]]
*[[Bool]]
*[[String]]
*[[Flowcharts]]
*[[Linked lists]]
*[[Functions]]
*[[Tables]]

Support:

*[[Request Lua Feature]]
*[[Bugs]]

[[Category:Scripting Tutorials]]
[[Category:Reference Pages]]

Scripting - Revision history

PRG at 22:06, 9 December 2024