创作者开发

写作 社区

技能解读

当前原文的自动摘译,尚未人工审校。

常用操作

动态添加组件: 获取组件: 加载场景: 加载资源:

参考文档

有关特定主题的详细信息,请参阅以下参考文件: 脚本基础知识:references/script-basics.md - TypeScript 设置、装饰器、类定义、属性声明 组件系统:references/component-system.md - 生命周期方法、组件管理、执行顺序 节点和层次结构:references/node-hierarchy.md - 节点创建、遍历、转换、坐标系

版本检查

始终确认用户使用的是 Cocos Creator 3.x,而不是 2.x。 API 和工作流程存在显着差异。

代码风格

专门使用 TypeScript(3.x 中不支持 JavaScript) 遵循装饰器模式:@ccclass、@property 对所有属性使用类型注释 对于当前节点访问优先选择 this.node

性能最佳实践

使用assetManager.releaseAsset()释放未使用的资源对频繁创建/销毁的节点使用对象池缓存组件引用而不是重复的getComponent()调用使用scheduleOnce而不是一次性延迟的计时器

流狐档案 运行与权限由流狐静态检查推断,不代表作者声明或实际测试结果。
领域
写作
作者声明的智能体
未找到明确声明;不据此推断已兼容或已测试
静态检查
88 / 100 · 启发式扫描,不代表运行安全
运行环境证据
未执行;当前没有隔离运行测试证据
作者 / 版本 / 许可证
@Dailiduzhou · 未声明许可证
上下文用量评级
低消耗
接入复杂程度
需简单配置
是否需要外部接口密钥
不需要
兼容的系统
macOS · Linux · Windows
运行环境要求
Node.js
检测到的文件与系统行为
  • 只读
  • 允许写入 / 修改
  • 命令执行
网络行为
仅限本地
安装命令数
无(仅作为资料)

需要注意: 未声明工具权限范围;实际权限由运行环境决定。

作者说明文件(原文) SKILL.md

# Cocos Creator 3.x Development Guide

Guide for Cocos Creator 3.x game development using TypeScript.

## Quick Start

### Basic Component Template

```typescript
import { _decorator, Component, Node } from 'cc';
const { ccclass, property } = _decorator;

@ccclass('MyComponent')
export class MyComponent extends Component {
    @property(Node)
    targetNode: Node = null;

    @property
    speed: number = 10;

    onLoad() {
        // Initialization
    }

    start() {
        // First frame update
    }

    update(deltaTime: number) {
        // Per-frame update
    }
}
```

### Common Operations

**Add component dynamically:**
```typescript
this.node.addComponent(MyComponent);
```

**Get component:**
```typescript
const comp = this.node.getComponent(MyComponent);
```

**Load scene:**
```typescript
director.loadScene('SceneName');
```

**Load resource:**
```typescript
resources.load('textures/sprite', SpriteFrame, (err, asset) => {
    this.node.getComponent(Sprite).spriteFrame = asset;
});
```

## Reference Documentation

For detailed information on specific topics, consult these reference files:

- **Script Basics**: [references/script-basics.md](references/script-basics.md) - TypeScript setup, decorators, class definitions, property declarations
- **Component System**: [references/component-system.md](references/component-system.md) - Lifecycle methods, component management, execution order
- **Node & Hierarchy**: [references/node-hierarchy.md](references/node-hierarchy.md) - Node creation, traversal, transformations, coordinate systems
- **Scene Management**: [references/scene-management.md](references/scene-management.md) - Scene loading, persist nodes, preloading
- **Resource Management**: [references/resource-management.md](references/resource-management.md) - Asset loading, releasing, Asset Bundles, memory management
- **Event System**: [references/event-system.md](references/event-system.md) - Input handling, custom events, node events

## Development Guidelines

### Version Check

Always confirm the user is working with **Cocos Creator 3.x**, not 2.x. APIs and workflows differ significantly.

### Code Style

- Use **TypeScript** exclusively (JavaScript not supported in 3.x)
- Follow decorator pattern: `@ccclass`, `@property`
- Use type annotations for all properties
- Prefer `this.node` for current node access

### Performance Best Practices

- Release unused resources with `assetManager.releaseAsset()`
- Use object pooling for frequently created/destroyed nodes
- Cache component references instead of repeated `getComponent()` calls
- Use `scheduleOnce` instead of timers for one-time delays

### Common Pitfalls

- **Lifecycle order**: `onLoad` → `start` → `update`. Don't access other components in `onLoad` if they might not be ready.
- **Resource leaks**: Always release dynamically loaded assets
- **Node activation**: Check `node.active` before accessing components
- **Scene switching**: Use persist nodes for data that needs to survive scene changes

## Key APIs Reference

### Node Operations
- `this.node` - Current node
- `this.node.parent` - Parent node
- `this.node.children` - Child nodes array
- `this.node.addChild(child)` - Add child node
- `this.node.removeFromParent()` - Remove from parent
- `this.node.destroy()` - Destroy node
- `this.node.setPosition(x, y, z)` - Set position
- `this.node.setRotation(x, y, z)` - Set rotation
- `this.node.setScale(x, y, z)` - Set scale

### Component Operations
- `this.node.addComponent(T)` - Add component
- `this.node.getComponent(T)` - Get component
- `this.getComponentInChildren(T)` - Get component in children
- `this.getComponentsInChildren(T)` - Get all components in children

### Scene Operations
- `director.loadScene(name)` - Load scene
- `director.preloadScene(name)` - Preload scene
- `director.getScene()` - Get current scene
- `game.addPersistRoot(node)` - Add persist node
- `game.removePersistRoot(node)` - Remove persist node

### Resource Operations
- `resources.load(path, type, callback)` - Load resource
- `assetManager.loadRemote(url, type, callback)` - Load remote resource
- `assetManager.releaseAsset(asset)` - Release resource
- `resources.loadDir(path, type, callback)` - Load directory

### Event Operations
- `this.node.on(type, callback, target)` - Register event
- `this.node.off(type, callback, target)` - Unregister event
- `this.node.emit(type, detail)` - Emit event
- `input.on(type, callback, target)` - Register input event

## External Resources

- **Official Manual**: https://docs.cocos.com/creator/3.8/manual/zh/
- **API Reference**: https://docs.cocos.com/creator/3.8/api/zh/
- **Example Projects**: https://github.com/cocos/cocos-example-projects

## Troubleshooting

### Component Not Found
- Verify component is attached in editor
- Check node is active: `if (this.node.active)`
- Use `getComponentInChildren()` for nested components

### Scene Not Loading
- Check scene name in Build Settings
- Verify scene is added to build
- Use `preloadScene()` for large scenes

### Memory Leaks
- Release assets after use
- Destroy unused nodes
- Remove event listeners in `onDestroy`
- Use Asset Bundles for modular loading

### Performance Issues
- Profile with Chrome DevTools
- Reduce draw calls with batching
- Use object pooling
- Optimize sprite atlases
- Check script execution time in updates

## When to Read References

Read specific reference files when:

- **script-basics.md**: Creating new components, defining properties, configuring TypeScript
- **component-system.md**: Implementing lifecycle callbacks, managing component dependencies
- **node-hierarchy.md**: Creating/destroying nodes, building scene hierarchy, coordinate transformations
- **scene-management.md**: Loading scenes, passing data between scenes, managing game flow
- **resource-management.md**: Loading assets, managing memory, using Asset Bundles
- **event-system.md**: Handling user input, implementing custom events, component communication

## Decision Guide

**Multiple valid approaches?** Use high freedom - provide options and let context guide choice.

**Standard pattern exists?** Use medium freedom - provide template code with parameters.

**Error-prone operation?** Use low freedom - provide specific, validated code pattern.

讨论

基于 GitHub Discussions。登录 GitHub 即可参与讨论、点赞、订阅更新。