Scripting assemblers

Assemblers are predefined instruction sets with built-in gameplay logic. In YAHAHA Studio (Studio), objects are controlled by components that are attached to them. Assemblers provide a simpler way of combining multiple components to create complex gameplay objects and logic.

You can use scripts to create your own assemblers. This enables you to introduce gameplay features, respond to user input, and modify existing functionality as desired, even if you don't have extensive coding knowledge. Whether you're a seasoned game developer or just starting out, assemblers can help you create games more easily, quickly, and efficiently.

This guide includes the following information to help you understand how to script an assembler:

• Scripting the Lua file.
  • Calling the assembler module.
  • Rendering UI elements.
  • Executing logic.
• Understanding the JSON file.
• Debugging an assembler.
• Reference.

Once you have created an assembler, an empty Lua file and a JSON file are generated, and you can start to write the Lua script in your code editor.

Scripting the Lua file

Studio supports Lua, a lightweight and embeddable scripting language for assemblers. Your Lua script for an assembler can include the following three parts:

Calling the assembler module

To integrate with the internal mechanics of Studio, a script must include the line require("assembler") in the header code to call the built-in assembler module.

Rendering UI elements

Studio supports various UI element types for rendering and collecting user input, which can be conveniently used as parameters to execute logic.

Here's an example of creating an integer input field and getting the user input:

-- Load the built-in assembler module in the header code
require("assembler")
-- Declare an empty table to store all assembler UI elements
-- Every new assembler UI element needs to be inserted into the 'actions' table separately
local actions = {}
-- Declare a variable "testValue" to store the user input value
local testValue

-- Render all UI elements in the 'actions' table
function render()
        -- Create an IntegerInput UI element with a default value of 100 
        local IntegerInput = assembler:New("IntegerInput", AssemblerUI.IntegerInput)
        IntegerInput.defaultValue = 100

        -- Define the action to take when the user interacts with the IntegerInput UI element
        -- This will store the user's selection in the "testValue" variable for later use
        IntegerInput.Action = function ()
            testValue = IntegerInput.GetInput() 
        end

        -- Add the IntegerInput UI element into the "actions" table for execution
        table.insert(actions,IntegerInput)

        -- Start to render all UI elements in the "actions" table
        for k, v in ipairs(actions) do
           v:Render(k)
        end

-- Execute all UI elements in the "actions"  table
function execute()
    print('start execute')
    -- Start to execute all Action methods of assembler UI elements after the user clicks 'Assemble'
     for k, v in ipairs(actions) do
        v.Action()
     end
 end

For more information on the assembler UI types and how to use them, see AssemblerUI.

Executing logic

Defining gameplay features involves writing the logic part of a script. For instance, you can edit a scene by adding assets using their asset IDs. Here's an example of how to do so:

require("assembler")
-- Create an asset with asset ID 274880352875 in your scene
function execute()
    local assetId = 274880352875
    local asset = createAsset(assetId) 
end

For more information on editing the scene with an assembler, see SceneEdit.

In addition, you can control components with the logic part of your script. Here's an example of how to add the Move component to an asset you create:

require("assembler")
function execute()
    -- Create an asset with asset ID 274880352875 in your scene
    local testObject = createAsset(274880352875)

    -- Add the Move component to the new object and store the data element of the component in the 'moveDataElement' variable
    local moveDataElement = addComponent(testObject, GameplayComponent.Move)
end

For more information on controlling components with an assembler, see Component Operation.

Understanding the JSON file

The JSON file contains non-logic basic information of the assembler, such as texts and dependencies. It is automatically generated and does not support editing locally.

Debugging an assembler

To check the assembler script, you run it by choosing it via My Resource>Local files>Assemblers. The Console window is automatically displayed in the bottom left corner and you should see the debug log automatically printed to the window's output.

Reference

To learn how to manage your own assembler, see Managing custom assemblers.