Scripting Capability Usage Guide

Because script editing is highly flexible, many errors are normally caught through a code editor or log output. However, we currently don't have a code editor in place, and the log output is currently limited.

To improve the scripting experience, we rely not only on support from R&D and QA, but also help from creators testing the feature in real scenarios. Your feedback is important and will help us identify and fix issues more quickly.

Product Specifications

1. Follow Script Requirements – Use the specifications outlined in the "User Script Specifications" section of the EH User Script External Opening Plan.
2. Avoid Duplicate Script Names – The script names must be unique. If a duplicate name is detected, the system will automatically rename and fix it.
3. Import Rules – When importing a script, you cannot have another script with the same name but a different file extension in the resource panel. The system will correct this automatically.
4. "require" Usage Rules
   • TS (TypeScript) scripts: Do not use require.
   • JS (JavaScript) scripts: Cannot require TS scripts.
5. Annotation Priority – If multiple annotations are applied to the same object, the last annotation closest to the object takes effect.
6. Port UI Behavior – In Port UIs, annotation types override others, especially for number fields.
7. Script Compilation Errors – If your script fails to compile, you'll receive an error in the log output.
8. Annotation Errors – The mistakes in annotations will show up as UI prompts.
9. Component Class Name Conflicts – Components with the same class name are considered duplicates and will not appear together in the component list.

Script Editing

• Recommended Code Editor: Use Visual Studio Code (VSCode) for the best experience.
• Required Plugin: Install the JavaScript and TypeScript Nightly extension from the VSCode marketplace to ensure compatibility with the latest language features.

  

API References

Go to the API references section for a list of supported APIs.

Logging

We support printing logs in scripts using the console module.

• Supported methods:
  • console.log()
  • console.info()

note

Log display in a pop-up or dedicated window is currently not supported in Effect House.

Where to Find Logs

You can view the output logs in the log files located 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

note

As of v5.0.0, a console window is now available in Effect House.

To open Console panel:

1. Go to the menu bar
2. Go to Windows
3. Click Console. The Console panel will open.

    

Usage Guide

Key Concepts

Entry Script File – This is the main script that defines a Component.

Script Editing

Create a New TS 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 New Script Component is added to the Assets panel, you can click on it to see a preview of the code in the Inspector panel.

Default Script Name

Component Script: NewBehaviourScript

Naming Convention Conflicts

Improper naming conventions may result in a variety of issues, including errors, conflicts, or non-compliance with specifications. Below are some common examples to be aware of.

Duplicate Resource File Names

When you import, rename, copy, or edit a script's class name and a resource with the same name already exists in the Asset Panel, the system will automatically rename the new file to avoid conflicts.

Resource File Name Does Not Comply with Specifications

When renaming a resource file, make sure the new name follows required naming rules. Otherwise, the system will show an error and won't allow the rename.

Example Error

If you try to rename a file like this:

NewBehaviourScript → NewBehaviourScript-1

You'll get a warning message: "The script name in the folder ./ is not correctly formatted. Please check and rename it according to the following rules: no characters other than letters, numbers, or underscores are allowed; the first character cannot be a number."

note

File Naming Conflict: .js vs .ts

• Files with the same name but different extensions (.js and .ts) cannot exist together. For example: Print.js and Print.ts are not allowed.
• If a conflict is detected, the system will automatically rename one of the files to avoid reference issues.

Script Writing

Open File for Editing

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

Option 1: Via the Assets panel	Option 2: Via the Inspector panel
1. Go to the Assets panel 2. Click NewBehaviourScript 3. Go to the Inspector panel 4. Click Open in external editor	1. Go to the Inspector panel 2. Find NewBehaviourScript 3. Click Edit

Referencing a Module Script File

For example, import a module script file Print.js that provides an add method for adding two numbers.

Port UI

The Port UI is defined by the input and output annotations.

Supported annotation types

type	Script Type	Annotation Parameter	Supported UI Elements
Basic Types
	boolean	bool	checkbox
	number	float, double, int	numberbox
	string	string	inputbox
APJS Types
	APJS.SceneObject	SceneObject	object_picker
	APJS.Transform	Transform	object_picker
	APJS.Vector2f	Vector2f	vec2
	APJS.Vector3f	Vector3f	vec3
	APJS.Vector4f	Vector4f	vec4
	APJS.Color	Color	color
	APJS.Texture	Texture	object_picker
	APJS.Prefab	Prefab	object_picker

Annotation parameters are either empty by default or must be one of the corresponding values in the list; any other value will result in an error.

Example Use Case

Script Component Creation

To create a Component Script (a script that can be attached to a scene), your user script must meet all of the following conditions:

1. The class starts with the @component annotation
2. The class ends with APJS.BasicScriptComponent
3. The script is written in TypeScript (.ts)

A user script that meets these conditions is referred to as a Component Script.

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 Asset panel, it becomes a usable component that can be attached to entities in your scene.

Currently, attaching is only supported via the Add Component button in the Inspector panel:

  

Example Use Case: Real-Time Effects

Script Component