Scripting

From Goodblox Wiki
Jump to navigationJump to search


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:

  1. Edit a place in GoodBlox Studio.

  2. Select View-->Toolbars-->Command from the menu bar.
    The Command toolbar will appear at the bottom of the screen.

  3. Select View-->Output from the menu bar.
    The Output panel will appear just above the Command toolbar.

  4. In the Command toolbar's textbox type the following:
    print("Hello World")
  5. 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:

  1. When a script calls wait(), the currently executing thread yields until the Event is fired. The return values from wait() are the Event arguments.

  2. 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.

See Also

In the beginning:...

Scripting Tutorials and Articles:

General Information:

Support: