Scripting Capability Usage Guide

APJS scripting lets you add TypeScript component scripts to an Effect House project. A component script is an exported class marked with @component() that extends APJS.BasicScriptComponent. Use it to read scene objects, respond to events, update 2D or 3D components, and expose creator-friendly Inspector controls.

Product Specifications

1. Use TypeScript for component scripts - Component scripts should be written in .ts files and should export one component class.
2. Declare component classes with @component() - The runtime discovers component scripts through the @component() decorator.
3. Extend APJS.BasicScriptComponent - Scene-attached scripts should inherit from APJS.BasicScriptComponent and use lifecycle methods such as onStart, onUpdate, and onDestroy.
4. Keep component class names unique - Components with the same class name are treated as duplicates and will not appear together in the component list.
5. Avoid duplicate script resource names - If a duplicate script name is detected, Effect House may automatically rename one of the resources.
6. Do not keep .js and .ts files with the same base name together - For example, Print.js and Print.ts should not coexist in the same script resource scope.
7. Do not use require in TypeScript component scripts - Use normal TypeScript/JavaScript module syntax where module scripting is supported.
8. Use serialized fields for Inspector wiring - Add @serializeProperty() to fields that creators should assign or tune in the Inspector.
9. Decorator order matters - When multiple Inspector decorators describe the same property, the decorator closest to the property is applied last.
10. Check the Console for compile and runtime issues - Type errors, decorator errors, and runtime logs are surfaced through Effect House logs and the Console panel.

Script Editing

• Recommended code editor: Use Visual Studio Code (VSCode) for the best editing experience.
• Recommended extension: Install the JavaScript and TypeScript Nightly extension from the VSCode Marketplace if your project depends on the latest TypeScript language support.

  

API References

Start with these APJS references when writing a component script:

• BasicScriptComponent - lifecycle base class for scene-attached scripts.
• Script Base tutorial - a runnable component starter project.
• Decorators - @component() and related decorators.
• Decorators tutorial - Inspector control patterns using serialized fields.
• SceneObject and Component - scene hierarchy and component access.
• Resources and Prefab - runtime resource loading and prefab instantiation.

The remaining pages in this API Reference section are generated from the current APJS declaration files and replace the older per-category API pages.

Logging

Use the standard console module for script logs.

• console.log()
• console.info()
• console.error()

note

Log display in a pop-up window is not supported. Use the Console panel or log files for debugging.

Where to Find Logs

You can view output logs in the cache directory.

// Mac log cache directory
/Users/bytedance/Library/Application Support/EffectHouse/UserData/logs

// Windows log cache directory
C:\Users\Admin\AppData\Roaming\EffectHouse\UserData\logs

  

Console Panel

To open the Console panel:

1. Go to the menu bar.
2. Go to Windows.
3. Click Console.

    

Usage Guide

Create a New TypeScript Script

To create a new Script Component:

1. Go to the Assets panel.
2. Click the Add asset button +.
3. Go to Script.
4. Click New Script Component.

After the Script Component is added to the Assets panel, select it to preview the code in the Inspector panel.

Default Script Name

New component scripts are commonly created with the default class name NewBehaviourScript. Rename the file and class to a unique, descriptive name before shipping your effect.

Naming Convention Conflicts

When you import, rename, copy, or edit a script class name and a resource with the same name already exists in the Assets panel, Effect House may automatically rename the new file to avoid conflicts.

When renaming a resource file, use letters, numbers, and underscores only. The first character cannot be a number.

For example, renaming NewBehaviourScript to NewBehaviourScript-1 will show a naming error because - is not allowed.

note

Files with the same base name but different script extensions, such as Print.js and Print.ts, should not exist together.

Open a Script for Editing

Depending on how you added the script resource, you have two ways to edit it:

Option 1: Assets panel	Option 2: Inspector panel
1. Go to the Assets panel. 2. Click the script asset. 3. Go to the Inspector panel. 4. Click Open in external editor.	1. Go to the Inspector panel. 2. Find the Script Component. 3. Click Edit.

Basic Component Pattern

@component()
export class TapCounter extends APJS.BasicScriptComponent {
  @serializeProperty()
  statusTextObject!: APJS.SceneObject;

  private statusText: APJS.Text | null = null;
  private count = 0;
  private onTouch = (event: APJS.IEvent) => {
    const touch = event.args[0] as APJS.TouchData;
    if (touch.phase !== APJS.TouchPhase.Began || !this.statusText) return;
    this.count += 1;
    this.statusText.text = "Taps: " + this.count;
  };

  onStart(): void {
    this.statusText = this.statusTextObject.getComponent("Text") as APJS.Text;
    APJS.EventManager.getGlobalEmitter().on(APJS.EventType.Touch, this.onTouch);
  }

  onDestroy(): void {
    APJS.EventManager.getGlobalEmitter().off(APJS.EventType.Touch, this.onTouch);
  }
}

Inspector Fields

Use @serializeProperty() on fields that should be assigned or tuned from the Inspector. Common serialized APJS field types include:

Type	Typical Inspector use
boolean	Toggle
number	Numeric input, slider, or spin box
string	Text input or text area
APJS.SceneObject	Object picker
APJS.Vector2f	2D vector field
APJS.Vector3f	3D vector field
APJS.Vector4f	4D vector field
APJS.Color	Color field
APJS.Texture	Texture object picker
APJS.Prefab	Prefab object picker

Use decorator helpers such as @header, @separator, @tooltip, @dropDown, @slider, @spinBox, @showIf, @textArea, and @readOnly to make serialized fields easier to use. See the Decorators tutorial for a runnable example.

Script Component Creation

To create a script that can be attached to a scene object, your user script must meet all of these conditions:

1. The component class is marked with @component().
2. The class extends APJS.BasicScriptComponent.
3. The script is written in TypeScript (.ts).

note

Only Component Scripts can be attached to objects in a scene.

Attaching the Script

Once a Component Script is created or imported through the Assets panel, it becomes a component that can be attached to entities in your scene. Attach it from the Add Component button in the Inspector panel.

  

Example Use Case: Real-Time Effects