Scripting: Difference between revisions

Revision as of 11:48, 24 September 2021

Up one category:
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 Forum.

Introduction

The GoodBlox scripting language is Lua 5.1, a concise and efficient scripting language used in games and embedded systems. Documentation on the language can be found at 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:

Intro to Scripting: Make a Dance Floor is a tutorial for beginners that shows how scripts can be used to control the color of parts. Also, when scripting it is also important to look at the Object Browser. Keep it open when you're making scripts in 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 Workspace or under parts, models, 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 GoodBlox 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:
```
print("Hello World")
```
Press the 'Enter' key.
The text "Hello World" appears in the 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 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 Workspace. If the script's property is under the DataModel, then it will also not run.

Environments and Libraries

Each Script has its own copy of the global Environment. This "sandboxes" each script. For instance another script cannot overwrite the global data defined in another script.

GoodBlox loads the following Lua standard libraries: Basic Functions, Coroutine Manipulation, String Manipulation, Table Manipulation, 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 GoodBlox 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 messages and hints.
GoodBlox can perform complex probelms for you.
This can make things extremely simple.

Here's a sample of basic math. Open up GoodBlox Studio, goto File> New, insert a Script into the Workspace, make sure that the Output is open.

Example:

a = 1 + 1 --'a' represents your math problem.
print(a) --This prints the result.

a = 5*5+1
print(a)

a = (9*9) + 19
print(a)

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

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

GoodBlox scripts use the basic Lua types nil, boolean, number, string, function, userdata, thread, and table. In addition, there are the following additional basic types:

Vector3

Vector3 represents a 3D vector. All properties are Read-Only.

Property	Type	Description
`x`	number	the x-coordinate
`y`	number	the y-coordinate
`z`	number	the z-coordinate
`unit`	Vector3	a normalized copy of the vector
`magnitude`	number	the length of the vector

Member Function	Description
`Vector3 lerp(Vector3 goal, number alpha)`	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.

Constructor	Description
`new()`	Creates an identity CFrame
`new(v)`	Creates CFrame from offset Vector3 v
`new(v, l)`	Creates CFrame from offset Vector3 v looking at point l
`new(x, y, z)`	Creates CFrame from offset (x, y, z)
`new(x, y, z, qx, qy, qz, qw)`	Creates CFrame from offset (x, y, z) and quaternion (qx, qy, qz, qw)
`new(x, y, z, R00, R01, R02, R10, R11, R12, R20, R21, R22)`	Creates CFrame from offset (x, y, z) and rotation matrix (R00, R01, R02, R10, R11, R12, R20, R21, R22)
`fromEulerAnglesXYZ(x, y, z)`	Creates a rotated CFrame (x, y, z) in radians
`fromAxisAngle(v, r)`	Creates a rotated CFrame from a unit vector and a rotation in radians

Property	Type	Description
`p`	Vector3	the translation
`x`	number	the x-component of translation
`y`	number	the y-component of translation
`z`	number	the z-component of translation
`lookVector`	Vector3	returns the facing direction along each axis

Member Function	Description
`CFrame inverse()`	returns the inverse of this CFrame
`CFrame toWorldSpace(CFrame)`	returns a CFrame transformed from Object to World coordinates. Also works with tuples
`CFrame toObjectSpace(CFrame)`	returns a CFrame transformed from World to Object coordinates. Also works with tuples
`Vector3 pointToWorldSpace(Vector3)`	returns a Vector3 transformed from Object to World coordinates. Also works with tuples
`Vector3 pointToObjectSpace(Vector3)`	returns a Vector3 transformed from World to Object coordinates. Also works with tuples
`Vector3 vectorToWorldSpace(Vector3)`	returns a Vector3 rotated from Object to World coordinates. Also works with tuples
`Vector3 vectorToObjectSpace(Vector3)`	returns a Vector3 rotated from World to Object coordinates. Also works with tuples

Operator	Description
`CFrame * CFrame`	returns composition of two CFrames
`CFrame * Vector3`	returns Vector3 transformed from Object to World coordinates
`CFrame + Vector3`	returns CFrame translated by Vector3
`CFrame - Vector3`	returns CFrame translated by -Vector3

Color3

Color3, sets color likely in Hex format (e.g. 1, 255, 98).

BrickColor

Function	Type	Description
`new`	BrickColor	returns a BrickColor (from a number, string, Color3 or r-g-b values)
`Random`	BrickColor	returns a random BrickColor
`White`	BrickColor	returns White
`Gray`	BrickColor	returns Gray
`DarkGray`	BrickColor	returns Dark Gray
`Black`	BrickColor	returns Black
`Red`	BrickColor	returns Red
`Yellow`	BrickColor	returns Yellow
`Green`	BrickColor	returns Green
`Blue`	BrickColor	returns Blue

Property	Type	Description
`Number`	number	The unique number that identifies the BrickColor
`Name`	string	the name associated with the BrickColor
`Color`	Color3	the Color3 associated with the BrickColor
`r`	number	the red component (between 0 and 1)
`g`	number	the green component (between 0 and 1)
`b`	number	the blue component (between 0 and 1)

Example:
local b = BrickColor.Yellow() print(b.r)
prints: 0.96078437566757

BrickColor Codes

File:GoodBloxColors.PNG [+] Use SirGelatina's Color Reference

Example:

-- 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()

Connection

Represents a connection to an Event

Globals

In addition to loading several Standard Libraries GoodBlox defines the following global variables:

game is the DataModel object that is the root of the tree for a Place.
workspace is the Workspace object that is a child of the DataModel.
script is the Script object that defines the script. (not applicable for the Command toolbar)
print() echoes each argument to the Output panel.
time() returns returns the current game time in seconds. (NOTE: THis function is scheduled for an upcoming release)
wait(t) 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.
delay(t,f) executes function "f" after "t" seconds have elapse. The function "f" is called with 2 arguments: The elapsed time and the current game time.

GoodBlox Objects

See Main List: [[Category:GoodBlox Lua Objects|GBX.lua Objects]

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

Properties

Object properties are accessed with the “dot” notation:

script.Name = "Hello"
print(script.Name)

Some properties are Read-Only. Attempting to assign to a read-only property will throw an error.

Functions

Member functions are called using the "colon" operator:

copy = script:clone()
print(copy.Name)

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

f = script.clone
copy = f(script)
print(copy.Name)

Note: If you are used to other scripting languages you will need remember to use : instead of . when invoking a member function. script.clone() will not behave as you might expect.

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

Here is some sample code:

-- 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()

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 onTouched() will be called each time Part is touched. However, once the Changed Event fires and the wait() 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 GoodBlox, and in addition to adding them through the GoodBlox 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 on the Forum. For more help, see the 'See Also' section at the bottom of the page.

@@ Line 336: / Line 336: @@
 -- 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>
+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.