Scene

Scene is the main part of Rethink, which makes working with Nature2D and in general working with UIs much more simpler and easier. It provides a simple API which can load in dozens of objects if required into the game with ease.

Custom Rigidbodies

Scene currently does not support the use of custom rigidbodies!

Properties¶

Symbols¶

Since: 0.6.0 Read-Only

Danger

Symbols must be wrapped with [ ]! Reason is that without the [ ] lua would just treat the index as a simple string and not as a table.

Symbols cannot be saved as locals! Reason is that symbols are automatically generated when indexing Scene.Symbols to make every instance of a symbol unique and prevent data loss by overriding another symbol.

Symbols are an easy way to add additional extra functionality to an object. This feature was inspired by Fusion. Rethink allows the creation of custom symbols. See: Scene.RegisterCustomSymbol()

Tag¶

Since: 0.6.0 Parameter: Tag(s) String | {String}

Gives object the specified tag(s) using CollectionService. Can be retrieved using CollectionService or Scene.GetFromTag().

Example

MyObject = {
    [Symbols.Tag] = "Hello world!"
}

local result1 = CollectionService:GetTagged("Hello world!")[1]
local result2 = Rethink.Scene.GetFromTag("Hello world!")[1]

print(result1 == result2) --> true

Results in the same object being returned. However, one key difference between CollectionService and GetFromTag is that GetFromTag returns the Rigidbody class whilst CollectionService would have just returned the gui instance (e.g. Frame) itself.

Property¶

Since: 0.6.0 Parameter: Properties {[String | Symbol]: any}

Adds properties and symbols to object. Mainly used in containers.

Example

MyContainer = {
    [Symbols.Property] = {
        Name = "Hello world!"
    },

    MyObject = {
        Name = "Something totally different!"
    }
}

From the example above, it is a normal behaviour that MyObject's name property was applied instead of the property symbol's. The reason is the Compiler always prioritizes objects more than containers.

Type¶

Since: 0.6.0 Parameter: Type String

Tells the Compiler the type of the object: UiBase or Rigidbody. Type symbols are defined in containers. If not present the Compiler will throw a warning and default to UIBase!

Example

MyContainer = {
    [Symbols.Type] = "Rigidbody"

    MyObject = {}
}

Event¶

Since: 0.6.0 Parameter: EventName String Parameter: Callback (Object) -> ()

Listens to the given event, firing the provided callback function with the object.

Example

MyObject = {
    [Symbols.Event("MouseEnter")] = function(thisObject)
        print("Mouse entered", thisObject.Name)
    end,
}

Permanent¶

Since: 0.6.2 Parameter: Predicate Boolean

Tells Scene if object should get flushed, if value is set to true. Symbol is ignored if ignorePermanent argument is set to true in Scene.Flush().

Example

MyObject = {
    [Symbols.Permanent] = true
}

Scene.Flush(false)

From the example above, it can be observed that MyObject has not been flushed, since Permanent was set to true and ignorePermanent was set to false. Resulting in the object staying in the scene. Leaving ignorePermanent as nil works the same way!

ShouldFlush¶

Since: 0.6.0 Parameter: Predicate Boolean

Danger

Renamed from ShouldFlush to Permanent for more clarity, since 0.6.2!

Tells Scene if object should get flushed, if value is set to false. Symbol is ignored if ignoreShouldFlush argument is set to true in Scene.Flush().

Example

MyObject = {
    [Symbols.ShouldFlush] = false
}

Scene.Flush()

From the example above, it can be observed that MyObject has not been flushed, since ShouldFlush and ignoreShouldFlush are set to false. Resulting in the object staying in the scene.

Rigidbody¶

Since: 0.6.0 Parameter: Properties {[String]: any}

Adds Rigidbody properties to object. This symbol has only affect to those who are under the Type symbol configured to Rigidbody. The Object property is being handled automatically.

Rigidbody properties of Nature2D

Example

MyObject = {
    [Symbols.Rigidbody] = {
        Anchored = true
    }
}

From the example above, once the physics simulation has been started the object wont move.

LinkTag¶

Since: 0.6.2 Parameter: Tag String

Adds a tag to object, which can be fetched using the LinkGet symbol.

Example

MyObject = {
    [Symbols.LinkTag] = "Hello world!"
}

LinkGet¶

Since: 0.6.2 Parameter: Tag String | { String } Parameter: Callback (Object, ...) -> ()

Gets all of the objects with the specified tag. If the symbol has been applied during loading of the scene, the execution will be delayed until LoadFinished has been fired else, when ObjectAdded fires.

Accepts an array of strings or a string as a parameter. If the given link name has more than one object tied to it, will return an array of the objects in the Callback function. Otherwise, the object itself will get returned.

Example

MyObject = {
    [Symbols.LinkTag] = "Hello world!"
},

NamedAfterMyobject = {
    Name = "Something totally different!",

    [Symbols.LinkGet({ "Hello world!" })] = function(thisObject, myObject: Frame)
        thisObject.Name = myObject.Name
    end
}

From the example above, after the scene has finished loading NamedAfterMyobject will rename itself from "Something totally different!" to "MyObject".

Class¶

Since: 0.6.2 Parameter: Type String

Tells the Compiler the class of the object (e.g. Frame). If not present, will default to Frame!

Example

MyTextLabel = {
    Text = "Hello world!",

    [Symbols.Class] = "TextLabel"
}

Children¶

Since: 0.6.2 Parameter: Children Table

Adds instances to the object, adding them to the scene and attaching symbols to them. Does not support the use of the Property symbol currently. The Type symbol can be used to specify the child instance's type.

Example

MyContainer = {
    MyRigidbody = {
        [Symbols.Type] = "Rigidbody",

        [Symbols.Children] = {
            RoundedCorner = {
                [Symbols.Class] = "UICorner"
            }
        }
    }
}

From the example above, a rigidbody gets created with an UICorner and gets parented to MyContainer.

IsLoading¶

Warning: Deprecated since 0.6.2 Read-Only

IsLoading is a simple property which tells if the compiler is busy or not working on a scene.

State¶

Since: 0.6.2 Read-Only

Replacement for IsLoading. Reports the current state of Scene:

Loading
Flushing
Standby

Events¶

Since: 0.5.3 Read-Only

Events are simple ways to run certain behaviour at certain times.

List of all available events

Name:	Description:
LoadStarted	Fires before the scene gets loaded
LoadFinished	Fires after the scene got loaded
FlushStarted	Fires before the scene gets flushed/deleted
FlushFinished	Fires after the scene got flushed/deleted
ObjectAdded	Fires when an object got added to the scene, returns object
ObjectRemoved	Fires when an object got removed from the scene, returns object

API¶

.Load(`sceneData`)¶

Since: 0.3.0 Parameter: sceneData Dictionary

Loads in a scene using the sceneData table. A name field must be provided, otherwise it will default to "Unnamed scene", which could cause unintended behaviours. The compiler does not check if a scene already exists with that name, meaning it will overwrite it. It is a good practice to have each container's type defined, even if it is supposed to be an UIBase! Otherwise, an error will be thrown!

Fires LoadStarted and LoadFinished.

Example

return {
    Name = "My scene",

    My_Container = {
        [Type] = "UIBase",
        [Property] = {
            Transparency = 0.5
            [Tag] = "Container!"
        }

        My_Object = {
            AnchorPoint = Vector2.new(0.5, 0.5),
            Position = UDim2.fromScale(0.5, 0.5),
            Size = UDim2.fromOffset(100, 100),

            [Tag] = "Object!"
        }
    },
}

How a scene module is typically structured:

Level	Name	Description
0	Main body	Defines the `Containers` as well as the `Name`
1	Containers	Defines the `Type` of the objects and the `Properties` that objects may share
2	Objects	Defines object properties and their symbols based on previous `Property` symbols present in `Containers` and the data inside the table itself

Objects always have higher priority when applying properties.

.Add(`object`, `symbols`)¶

Since: 0.5.3 Parameter: object GuiObject | Rigidbody Parameter: symbols {[Symbol]: Any}

Internally used by scene when the compiler has finished gathering and building up the objects in the scene. Sets up a cleanup method for the object, creates a new entry in the sceneObjects array saving an ObjectReference table associated with the object and calls Scene.AddSymbols().

Fires ObjectAdded.

type ObjectReference = {
    Object: GuiObject | Rigidbody,
    Janitor: Janitor,
    SymbolJanitor: Janitor,
    ID: string,
    Symbols: {
        IDs: { UUID }?,
        Permanent: boolean?,
        LinkIDs: { string }?,
    },
}

.AddSymbols(`object`, `symbols`)¶

Since: 0.6.0 Parameter: object GuiObject | Rigidbody Parameter: symbols {[Symbol]: Any}

Attaches symbols to an object. Used by Scene.Add(). Does not support custom objects, due to symbols need to have the reference to the object to access data such as the object's Janitor.

.Remove(`object`, `stripSymbols`)¶

Since: 0.6.0 Parameter: object GuiObject | Rigidbody Parameter: stripSymbols Boolean Default: stripSymbols False

Removes the object from the scene without destroying it nor cleaning up the Janitor. If stripSymbols is set to true it will cleanup the symbols.

Fires ObjectRemoved.

.Cleanup(`object`)¶

Since: 0.6.2 Parameter: object GuiObject | Rigidbody

Cleans up the provided object.

.Flush(`ignorePermanent`)¶

Since: 0.5.3 Parameter: ignorePermanent Boolean Default: ignorePermanent False

Cleans up all of the objects in the scene if called. If ignorePermanent is set to true Scene will ignore objects which have the Permanent symbol attached with the value of true.

.RegisterCustomSymbol(`name`, `returnKind`, `controller`)¶

Since: 0.6.2 Parameter: name String Parameter: returnKind Number Parameter: controller (object, symbol) -> ()

Registers a new custom symbol handler. The returnKind parameter accepts:

0 - Returns the symbol
1 - Returns a function, when called returns the symbol

Example

This example prints the object's ID and the attached value of the symbol.

Scene.RegisterCustomSymbol("testSymbol", 0, function(object, symbol)
    print(object.ID, symbol.SymbolData.Attached)
end)

.GetFromTag(`tag`)¶

Since: 0.6.0 Parameter: tag String Returns: Objects {[Number]: GuiBase2d | Types.Rigidbody}

Returns all of the objects with the specified tag.

.IsRigidbody(`object`)¶

Since: 0.6.0 Parameter: object GuiObject | Rigidbody Returns: Result Boolean

Returns a boolean to indicate if object is a rigidbody or not.

.GetObjectReference(`object`)¶

Since: 0.6.0 Parameter: object GuiObject | Rigidbody Returns: Reference ObjectReference

Returns the object's ObjectReference table used by Scene.

Useful to add custom events or logic to the object and making it sure that, that event/logic gets disconnected upon the destruction of the object.

Internally used by Scene.AddSymbols().

.GetObjects()¶

Since: 0.5.3 Returns: Objects { [Types.UUID]: ObjectReference }

Returns all of the objects wihin scene containing all of the ObjectReferences.

Scene

Properties¶

Symbols¶

Tag¶

Property¶

Type¶

Event¶

Permanent¶

ShouldFlush¶

Rigidbody¶

LinkTag¶

LinkGet¶

Class¶

Children¶

IsLoading¶

State¶

Events¶

API¶

.Load(sceneData)¶

.Add(object, symbols)¶

.AddSymbols(object, symbols)¶

.Remove(object, stripSymbols)¶

.Cleanup(object)¶

.Flush(ignorePermanent)¶

.RegisterCustomSymbol(name, returnKind, controller)¶

.GetFromTag(tag)¶

.IsRigidbody(object)¶

.GetObjectReference(object)¶

.GetObjects()¶

.Load(`sceneData`)¶

.Add(`object`, `symbols`)¶

.AddSymbols(`object`, `symbols`)¶

.Remove(`object`, `stripSymbols`)¶

.Cleanup(`object`)¶

.Flush(`ignorePermanent`)¶

.RegisterCustomSymbol(`name`, `returnKind`, `controller`)¶

.GetFromTag(`tag`)¶

.IsRigidbody(`object`)¶

.GetObjectReference(`object`)¶