Tài liệu Needle Engine
Downloads
  • What is Needle Engine?
  • Lời chứng thực
  • Get an overview

    • Samples and Showcase
    • Tầm nhìn của chúng tôi 🔮
    • Tổng quan tính năng
    • Tổng quan kỹ thuật
  • Resources

    • Pricing and Plans
    • Changelog
    • API Documentation
    • Support & Community
  • Integrations

    • Needle Engine cho Unity
    • Needle Engine cho Blender
    • Needle Engine dưới dạng Web Component
    • Needle Engine trên Trang web của bạn
    • Needle Cloud
  • Core Concepts

    • Cấu trúc dự án Needle Engine
    • Everywhere Actions
    • Xuất Tài sản sang glTF
    • Frameworks, Bundlers, HTML
    • Kiểm thử trên thiết bị cục bộ
    • Triển khai và Tối ưu hóa
  • Advanced

    • VR & AR (WebXR)
    • Image Tracking (WebXR)
    • Kết nối mạng
    • MaterialX
    • Editor Sync
  • Troubleshooting

    • Cách Gỡ Lỗi
    • Câu hỏi thường gặp (FAQ) 💡
    • Support and Community
  • Videos

    • Tutorials on Youtube
    • Interviews on Youtube
  • Scripting Overview

    • Scripting trong Needle Engine
    • Giới thiệu về Scripting cho các nhà phát triển Unity
    • Needle Core Components
    • Everywhere Actions
  • Components and Lifecycle

    • Creating and using Components
    • @serializable và các decorator khác
    • Tự động tạo Component
    • Ví dụ về Scripting
    • Community Contributions
    • Các Module Bổ Sung
  • Settings and APIs

    • Cấu hình <needle-engine>
    • needle.config.json
    • Needle Engine API
    • three.js API
Help
Samples
Pricing
  • Needle Website
  • Needle Cloud
  • Support Community
  • Discord Server
  • X/Twitter
  • YouTube
  • Newsletter
  • Email
  • Feedback
  • Github
  • English
  • 简体中文
  • Español
  • Português
  • Français
  • हिन्दी
  • 日本語
  • Deutsch
  • Tiếng Việt
Downloads
  • What is Needle Engine?
  • Lời chứng thực
  • Get an overview

    • Samples and Showcase
    • Tầm nhìn của chúng tôi 🔮
    • Tổng quan tính năng
    • Tổng quan kỹ thuật
  • Resources

    • Pricing and Plans
    • Changelog
    • API Documentation
    • Support & Community
  • Integrations

    • Needle Engine cho Unity
    • Needle Engine cho Blender
    • Needle Engine dưới dạng Web Component
    • Needle Engine trên Trang web của bạn
    • Needle Cloud
  • Core Concepts

    • Cấu trúc dự án Needle Engine
    • Everywhere Actions
    • Xuất Tài sản sang glTF
    • Frameworks, Bundlers, HTML
    • Kiểm thử trên thiết bị cục bộ
    • Triển khai và Tối ưu hóa
  • Advanced

    • VR & AR (WebXR)
    • Image Tracking (WebXR)
    • Kết nối mạng
    • MaterialX
    • Editor Sync
  • Troubleshooting

    • Cách Gỡ Lỗi
    • Câu hỏi thường gặp (FAQ) 💡
    • Support and Community
  • Videos

    • Tutorials on Youtube
    • Interviews on Youtube
  • Scripting Overview

    • Scripting trong Needle Engine
    • Giới thiệu về Scripting cho các nhà phát triển Unity
    • Needle Core Components
    • Everywhere Actions
  • Components and Lifecycle

    • Creating and using Components
    • @serializable và các decorator khác
    • Tự động tạo Component
    • Ví dụ về Scripting
    • Community Contributions
    • Các Module Bổ Sung
  • Settings and APIs

    • Cấu hình <needle-engine>
    • needle.config.json
    • Needle Engine API
    • three.js API
Help
Samples
Pricing
  • Needle Website
  • Needle Cloud
  • Support Community
  • Discord Server
  • X/Twitter
  • YouTube
  • Newsletter
  • Email
  • Feedback
  • Github
  • English
  • 简体中文
  • Español
  • Português
  • Français
  • हिन्दी
  • 日本語
  • Deutsch
  • Tiếng Việt
  • Getting Started

    • Downloads
    • Needle Engine for Unity
    • Needle Engine for Blender
    • Needle Engine as Web Component
    • Needle Engine on your Website
    • Needle Cloud
    • Custom integrations
    • Support and Community
  • Core Concepts

    • Cấu trúc dự án Needle Engine
    • Everywhere Actions
    • Xuất Tài sản sang glTF
    • Frameworks, Bundlers, HTML
    • Kiểm thử trên thiết bị cục bộ
    • Triển khai và Tối ưu hóa
  • Scripting

    • Scripting trong Needle Engine
    • Giới thiệu về Scripting cho các nhà phát triển Unity
    • Creating and using Components
    • Tự động tạo Component
    • Ví dụ về Scripting
    • Community Contributions
  • Advanced

    • VR & AR (WebXR)
    • Image Tracking (WebXR)
    • Kết nối mạng
    • MaterialX
    • Editor Sync
  • Troubleshooting

    • Cách Gỡ Lỗi
    • Câu hỏi thường gặp (FAQ) 💡
    • Support and Community
  • Reference

    • Tổng quan tính năng
    • Tổng quan kỹ thuật
    • Needle Core Components
    • needle.config.json
    • Cấu hình <needle-engine>
    • @serializable và các decorator khác

Tự động tạo các Component Editor

Khi làm việc trong Unity hoặc Blender, bạn sẽ nhận thấy rằng khi tạo một Needle Engine component mới bằng Typescript hoặc Javascript, nó sẽ tự động tạo một Unity C# stub component HOẶC một Blender panel cho bạn.

Điều này là nhờ sự kỳ diệu của Needle component compiler chạy ngầm trong môi trường Editor và theo dõi các thay đổi đối với tệp script của bạn. Khi nó nhận thấy bạn đã tạo một Needle Engine component mới, nó sẽ tạo ra component Unity hoặc Blender panel tương ứng, bao gồm các biến public hoặc properties mà bạn có thể đặt hoặc liên kết từ bên trong Editor.

Lưu ý: Component compiler hiện tại chỉ tạo component. Vì vậy, nếu bạn cần expose một Typescript Enum trong Unity, bạn có thể thêm nó vào C# của mình theo cách thủ công trong một tệp C# mới hoặc bên ngoài mã được tạo (xem ví dụ bên dưới)

Kiểm soát việc tạo component

Bạn có thể sử dụng các comment sau trong mã Typescript của mình để kiểm soát hành vi tạo mã C#:

Thuộc tínhKết quả
// @generate-componentBuộc tạo class tiếp theo
// @dont-generate-componentVô hiệu hóa việc tạo class tiếp theo, điều này hữu ích trong trường hợp bạn đã có script C# hiện có trong dự án của mình
// @serializeFieldThêm thuộc tính [SerializeField] vào trường được tạo
// @type UnityEngine.CameraChỉ định kiểu trường C# được tạo
// @nonSerializedBỏ qua việc tạo trường hoặc phương thức tiếp theo

Ví dụ

Buộc component compiler tạo trường C# AudioClip có tên myAudioClip

import { Behaviour, serializable } from "@needle-tools/engine";

export class MyComponent extends Behaviour {
	//@type UnityEngine.AudioClip
	@serializable()
	myAudioClip?: string;
}

Buộc component compiler kế thừa từ một lớp con cụ thể

import { Behaviour } from "@needle-tools/engine";
export class MyCustomBaseClass extends Behaviour { /* ... */ }
// ---cut-before---
//@type MyNamespace.MyCustomBaseClass
export class MyComponent extends MyCustomBaseClass {
}

Component Compiler trong Unity

Nếu bạn muốn thêm script bên trong thư mục src/scripts trong dự án của mình, bạn cần có một Component Generator trên GameObject chứa component ExportInfo của bạn. Bây giờ, khi thêm các component mới vào your/threejs/project/src/scripts nó sẽ tự động tạo các script Unity trong Assets/Needle/Components.codegen. Nếu bạn muốn thêm script vào bất kỳ tệp NpmDef nào, bạn chỉ cần tạo chúng - mỗi NpmDef tự động theo dõi các thay đổi script và xử lý việc tạo component, vì vậy bạn không cần bất kỳ component bổ sung nào trong scene của mình.

Để các trường C# được tạo đúng cách, hiện tại điều quan trọng là bạn phải khai báo rõ ràng kiểu Typescript. Ví dụ: myField : number = 5

Bạn có thể chuyển đổi giữa đầu vào Typescript và các C# stub component được tạo bằng cách sử dụng các tab bên dưới

Typescript
import { AssetReference, Behaviour, serializable } from "@needle-tools/engine";
import { Object3D } from "three";

export class MyCustomComponent extends Behaviour {
    @serializable()
    myFloatValue: number = 42;

    @serializable(Object3D)
    myOtherObject?: Object3D;

    @serializable(AssetReference)
    prefabs: AssetReference[] = [];

    start() {
        this.sayHello();
    }

    private sayHello() {
        console.log("Hello World", this);
    }
}
Generated C
// NEEDLE_CODEGEN_START
// auto generated code - do not edit directly

#pragma warning disable

namespace Needle.Typescript.GeneratedComponents
{
	public partial class MyCustomComponent : UnityEngine.MonoBehaviour
	{
		public float @myFloatValue = 42f;
		public UnityEngine.Transform @myOtherObject;
		public UnityEngine.Transform[] @prefabs = new UnityEngine.Transform[]{ };
		public void start(){}
		public void update(){}
	}
}

// NEEDLE_CODEGEN_END
Extending Generated C
using UnityEditor;

// you can add code above or below the NEEDLE_CODEGEN_ blocks

// NEEDLE_CODEGEN_START
// auto generated code - do not edit directly

#pragma warning disable

namespace Needle.Typescript.GeneratedComponents
{
	public partial class MyCustomComponent : UnityEngine.MonoBehaviour
	{
		public float @myFloatValue = 42f;
		public UnityEngine.Transform @myOtherObject;
		public UnityEngine.Transform[] @prefabs = new UnityEngine.Transform[]{ };
		public void start(){}
		public void update(){}
	}
}

// NEEDLE_CODEGEN_END

namespace Needle.Typescript.GeneratedComponents
{
    // This is how you extend the generated component (namespace and class name must match!)
	public partial class MyCustomComponent : UnityEngine.MonoBehaviour
	{
		
		public void MyAdditionalMethod()
		{
		}

		private void OnValidate()
		{
			myFloatValue = 42;
		}
	}

    // of course you can also add custom editors
	[CustomEditor(typeof(MyCustomComponent))]
	public class MyCustomComponentEditor : Editor
	{
		public override void OnInspectorGUI()
		{
			EditorGUILayout.HelpBox("This is my sample component", MessageType.None);
			base.OnInspectorGUI();
		}
	}
}

Mở rộng các component đã tạo

Các lớp C# component được tạo với cờ partial để dễ dàng mở rộng chúng với chức năng. Điều này hữu ích để vẽ gizmos, thêm context menus hoặc thêm các trường hoặc phương thức bổ sung không phải là một phần của component tích hợp sẵn.

Quy tắc viết hoa/thường thành viên

Các thành viên được export sẽ bắt đầu bằng một chữ cái thường. Ví dụ, nếu thành viên C# của bạn có tên MyString, nó sẽ được gán cho myString.

Trang được dịch tự động bằng AI

Suggest changes
Last Updated: 6/11/25, 12:25 PM
Prev
Creating and using Components
Next
Ví dụ về Scripting