Skip to main content

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.
  1. Annotation Priority – If multiple annotations are applied to the same object, the last annotation closest to the object takes effect.
  2. Port UI Behavior – In Port UIs, annotation types override others, especially for number fields.
  3. Script Compilation Errors – If your script fails to compile, you'll receive an error in the log output.
  4. Annotation Errors – The mistakes in annotations will show up as UI prompts.
  5. 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.
type script  new behaviour script

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()
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
log files  log files

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.
navigating console panel  navigating console panel  navigating console panel

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
create a new ts script

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.

assets create ts script

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.

duplicate script names

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:

NewBehaviourScriptNewBehaviourScript-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."

example error
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 panelOption 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

Assets panel

1. Go to the Inspector panel

2. Find NewBehaviourScript

3. Click Edit

Assets panel

Referencing a Module Script File

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

reference module script

Port UI

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

Supported annotation types

typeScript TypeAnnotation ParameterSupported UI Elements
Basic Types
booleanboolcheckbox
numberfloat, double, intnumberbox
stringstringinputbox
APJS Types
APJS.SceneObjectSceneObjectobject_picker
APJS.TransformTransformobject_picker
APJS.Vector2fVector2fvec2
APJS.Vector3fVector3fvec3
APJS.Vector4fVector4fvec4
APJS.ColorColorcolor
APJS.TextureTextureobject_picker
APJS.PrefabPrefabobject_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

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)
component script

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:

add component from inspector  add component from inspector added

Example Use Case: Real-Time Effects

Script Component

example use case of real time effects
Copyright © 2025 TikTok. All rights reserved.
About TikTokHelp CenterCareersContactLegalCookies