创作者开发
- 作者仓库星标 29
- 作者仓库 cocos-creator-dev-skill
- 领域
- 写作
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @Dailiduzhou · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 需简单配置
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- macOS · Linux · Windows
- 运行环境要求
- Node.js
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 命令执行
- 网络行为
- 仅限本地
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
# 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.
章节与文件索引
按说明文件中的顺序排列。
常用操作
参考文档
版本检查
代码风格
性能最佳实践
文件/命令 -> @ccclass · @property · this.node · assetManager.releaseAsset() · getComponent() · scheduleOnce · onLoad · start
内容校验值 -> c137499317a3
当前原文的自动摘译,尚未人工审校。
常用操作
动态添加组件: 获取组件: 加载场景: 加载资源:
参考文档
有关特定主题的详细信息,请参阅以下参考文件: 脚本基础知识: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而不是一次性延迟的计时器