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
- Follow Script Requirements – Use the specifications outlined in the "User Script Specifications" section of the EH User Script External Opening Plan.
- Avoid Duplicate Script Names – The script names must be unique. If a duplicate name is detected, the system will automatically rename and fix it.
- 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.
- "require" Usage Rules
- TS (TypeScript) scripts: Do not use require.
- JS (JavaScript) scripts: Cannot require TS scripts.
- Annotation Priority – If multiple annotations are applied to the same object, the last annotation closest to the object takes effect.
- Port UI Behavior – In Port UIs, annotation types override others, especially for number fields.
- Script Compilation Errors – If your script fails to compile, you'll receive an error in the log output.
- Annotation Errors – The mistakes in annotations will show up as UI prompts.
- 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 list of supported APIs.
Logging
We support printing logs in scripts using the console
module.
- Supported methods:
console.log()
console.info()
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
As of v5.0.0, a console window is now available in Effect House.
To open Console panel:
- Go to the menu bar
- Go to Windows
- 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:
- Go to the Assets panel
- Click the Add asset button [+]
- Go to Script
- 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."

File Naming Conflict: .js
vs .ts
- Files with the same name but different extensions (
.js
and.ts
) cannot exist together. For example:Print.js
andPrint.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:
- The class starts with the
@component
annotation - The class ends with
APJS.BasicScriptComponent
- The script is written in TypeScript (
.ts
)

A user script that meets these conditions is referred to as a Component Script.
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
