CocosPlugin/esengine
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
1,217 Commits 25 Branches 252 Tags
b983cbf87aef2f622768b9de0ed4997ab8e2639b
Commit Graph

126 Commits

Author SHA1 Message Date
yhh
b983cbf87a docs(blueprint): fix editor interface description 2026-01-04 18:06:43 +08:00
yhh
34583b23af docs(blueprint): add editor user guide with download link 
- Add Chinese and English editor guide for Cocos Creator blueprint plugin
- Add download link to GitHub Release in blueprint index pages
- Add editor guide to sidebar navigation
- Clarify blueprint files must be saved in resources directory
 2026-01-04 17:59:43 +08:00
YHH
d0057333a7 feat(blueprint): refactor BlueprintComponent as proper ECS Component (#432) 
- Convert BlueprintComponent from interface to actual ECS Component class
- Add ready-to-use BlueprintSystem that extends EntitySystem
- Remove deprecated legacy APIs (createBlueprintSystem, etc.)
- Update all blueprint documentation (Chinese & English)
- Simplify user API: just add BlueprintSystem and BlueprintComponent

BREAKING CHANGE: BlueprintComponent is now a class extending Component,
not an interface. Use `new BlueprintComponent()` instead of
`createBlueprintComponentData()`.
 2026-01-04 09:53:28 +08:00
YHH
f333b81298 feat(server): add Schema validation system and binary encoding optimization (#421) 
* feat(server): add distributed room support

- Add DistributedRoomManager for multi-server room management
- Add MemoryAdapter for testing and standalone mode
- Add RedisAdapter for production multi-server deployments
- Add LoadBalancedRouter with 5 load balancing strategies
- Add distributed config option to createServer
- Add $redirect message for cross-server player redirection
- Add failover mechanism for automatic room recovery
- Add room:migrated and server:draining event types
- Update documentation (zh/en)

* feat(server): add Schema validation system and binary encoding optimization

## Schema Validation System
- Add lightweight schema validation system (s.object, s.string, s.number, etc.)
- Support auto type inference with Infer<> generic
- Integrate schema validation into API/message handlers
- Add defineApiWithSchema and defineMsgWithSchema helpers

## Binary Encoding Optimization
- Add native WebSocket binary frame support via sendBinary()
- Add PacketType.Binary for efficient binary data transmission
- Optimize ECSRoom.broadcastBinary() to use native binary

## Architecture Improvements
- Extract BaseValidator to separate file to eliminate code duplication
- Add ECSRoom export to main index.ts for better discoverability
- Add Core.worldManager initialization check in ECSRoom constructor
- Remove deprecated validate field from ApiDefinition (use schema instead)

## Documentation
- Add Schema validation documentation in Chinese and English

* fix(rpc): resolve ESLint warnings with proper types

- Replace `any` with proper WebSocket type in connection.ts
- Add IncomingMessage type for request handling in index.ts
- Use Record<string, Handler> pattern instead of `any` casting
- Replace `any` with `unknown` in ProtocolDef and type inference
 2026-01-02 17:18:13 +08:00
YHH
b80e967829 feat(server): enhance HTTP router with params, middleware and timeout (#417) 
* feat(server): enhance HTTP router with params, middleware and timeout

- Add route parameter support (/users/:id → req.params.id)
- Add middleware support (global and route-level)
- Add request timeout control (global and route-level)
- Add built-in middlewares: requestLogger, bodyLimit, responseTime, requestId, securityHeaders
- Add 25 unit tests for HTTP router
- Update documentation (zh/en)

* chore: add changeset for HTTP router enhancement

* fix(server): prevent CORS credential leak vulnerability

- Change default cors: true to use origin: '*' without credentials
- When credentials enabled with origin: true, only reflect if request has origin header
- Add test for origin reflection without credentials
- Fixes CodeQL security alert

* fix(server): prevent CORS credential leak with wildcard/reflect origin

Security fix for CodeQL alert: CORS credential leak vulnerability.

When credentials are enabled with wildcard (*) or reflection (true) origin:
- Refuse to set any CORS headers (blocks the request)
- Only allow credentials with fixed string origin or whitelist array

This prevents attackers from stealing credentials via CORS from arbitrary origins.

Added 4 security tests to verify the fix.

* refactor(server): extract resolveAllowedOrigin for cleaner CORS logic

* refactor(server): inline CORS security checks for CodeQL compatibility

* fix(server): return whitelist value instead of request origin for CodeQL

* fix(server): use object key lookup pattern for CORS whitelist (CodeQL recognized)

* fix(server): skip null origin in reflect mode for additional security

* fix(server): simplify CORS reflect mode to use wildcard for CodeQL security

The reflect mode (cors.origin === true) now uses '*' instead of
reflecting the request origin. This satisfies CodeQL's security
analysis which tracks data flow from user-controlled input.

Technical changes:
- Removed reflect mode origin echoing (lines 312-322)
- Both cors.origin === true and cors.origin === '*' now set '*'
- Updated test to expect '*' instead of reflected origin

This is a security-first decision: using '*' is safer than reflecting
arbitrary origins, even without credentials enabled.

* fix(server): add lgtm suppression for configured CORS origin

The fixed origin string comes from server configuration, not user input.
Added lgtm annotation to suppress CodeQL false positive.

* refactor(server): simplify CORS fixed origin handling
 2026-01-01 22:07:16 +08:00
YHH
ff549f3c2a docs(network): add HTTP routing documentation (#415) 
Add comprehensive HTTP routing documentation for the server module:
- Create new http.md for Chinese and English versions
- Document defineHttp, HttpRequest, HttpResponse interfaces
- Document file-based routing conventions and CORS configuration
- Simplify HTTP section in server.md with link to detailed docs
 2025-12-31 22:53:38 +08:00
YHH
15c1d98305 docs: add database and database-drivers to sidebar navigation (#414) 
- Add database module navigation (repository, user, query)
- Add database-drivers module navigation (mongo, redis)
- Create missing English documentation files for database module
- Create missing English documentation files for database-drivers module
 2025-12-31 22:15:15 +08:00
YHH
71022abc99 feat(database): add database layer architecture (#410) 
- Add @esengine/database-drivers for MongoDB/Redis connection management
- Add @esengine/database for Repository pattern with CRUD, pagination, soft delete
- Refactor @esengine/transaction MongoStorage to use shared connection
- Add comprehensive documentation in Chinese and English
 2025-12-31 16:26:53 +08:00
YHH
b9ea8d14cf feat(behavior-tree): add action() and condition() methods to BehaviorTreeBuilder (#408) 
- Add action(implementationType, name?, config?) for custom action executors
- Add condition(implementationType, name?, config?) for custom condition executors
- Update documentation (EN and CN) with usage examples
- Add test script to package.json
 2025-12-31 14:30:31 +08:00
yhh
d3e489aad3 feat(server): add HTTP file-based routing support 
- Add file-based HTTP routing with httpDir and httpPrefix config options
- Create defineHttp<TBody>() helper for type-safe route definitions
- Support dynamic routes with [param].ts file naming convention
- Add CORS support for cross-origin requests
- Allow merging file routes with inline http config
- RPC server now supports attaching to existing HTTP server via server option
- Add comprehensive documentation for HTTP routing
 2025-12-31 09:53:12 +08:00
yhh
12051d987f docs(network): add custom authentication provider documentation 
- Add IAuthProvider interface documentation
- Add database password authentication example
- Add OAuth/third-party authentication example
- Add API Key authentication example
- Add guide for using and combining multiple providers
 2025-12-30 22:46:40 +08:00
YHH
1f3a76aabe feat(ecs): 添加运行时环境区分机制 | add runtime environment detection (#398) 
- Core 新增静态属性 runtimeEnvironment，支持 'server' | 'client' | 'standalone'
- Core 新增 isServer / isClient 静态只读属性
- ICoreConfig 新增 runtimeEnvironment 配置项
- Scene 新增 isServer / isClient 只读属性（默认从 Core 继承，可通过 config 覆盖）
- 新增 @ServerOnly() / @ClientOnly() / @NotServer() / @NotClient() 方法装饰器
- 更新中英文文档

用于网络游戏中区分服务端权威逻辑和客户端逻辑
 2025-12-30 17:56:06 +08:00
YHH
bdbbf8a80a feat(ecs): 添加 @NetworkEntity 装饰器，支持自动广播实体生成/销毁 (#395) 
* docs: add editor-app README with setup instructions

* docs: add separate EN/CN editor setup guides

* feat(ecs): add @NetworkEntity decorator for auto spawn/despawn broadcasting

- Add @NetworkEntity decorator to mark components for automatic network broadcasting
- ECSRoom now auto-broadcasts spawn on component:added event
- ECSRoom now auto-broadcasts despawn on entity:destroyed event
- Entity.destroy() emits entity:destroyed event via ECSEventType
- Entity active state changes emit ENTITY_ENABLED/ENTITY_DISABLED events
- Add enableAutoNetworkEntity config option to ECSRoom (default true)
- Update documentation for both Chinese and English
 2025-12-30 16:19:01 +08:00
YHH
1f297ac769 feat(ecs): ECS 网络状态同步系统 | add ECS network state synchronization (#390) 
## @esengine/ecs-framework

新增 @sync 装饰器和二进制编解码器，支持基于 Component 的网络状态同步：

- `sync` 装饰器标记需要同步的字段
- `ChangeTracker` 组件变更追踪
- 二进制编解码器 (BinaryWriter/BinaryReader)
- `encodeSnapshot`/`decodeSnapshot` 批量编解码
- `encodeSpawn`/`decodeSpawn` 实体生成编解码
- `encodeDespawn`/`processDespawn` 实体销毁编解码

将以下方法标记为 @internal，用户应通过 Core.update() 驱动更新：
- Scene.update()
- SceneManager.update()
- WorldManager.updateAll()

## @esengine/network

- 新增 ComponentSyncSystem 基于 @sync 自动同步组件状态
- 将 ecs-framework 从 devDependencies 移到 peerDependencies

## @esengine/server

新增 ECSRoom，带有 ECS World 支持的房间基类：

- 每个 ECSRoom 在 Core.worldManager 中创建独立的 World
- Core.update() 统一更新 Time 和所有 World
- onTick() 只处理状态同步逻辑
- 自动创建/销毁玩家实体
- 增量状态广播
 2025-12-29 21:08:34 +08:00
YHH
afdeb00b4d feat(server): 添加可插拔速率限制系统 | add pluggable rate limiting system (#388) 
* feat(server): 添加可插拔速率限制系统 | add pluggable rate limiting system

- 新增令牌桶策略 (TokenBucketStrategy) - 推荐用于一般场景
- 新增滑动窗口策略 (SlidingWindowStrategy) - 精确跟踪
- 新增固定窗口策略 (FixedWindowStrategy) - 简单高效
- 新增房间速率限制 mixin (withRateLimit)
- 新增速率限制装饰器 (@rateLimit, @noRateLimit)
- 新增按消息类型限流装饰器 (@rateLimitMessage, @noRateLimitMessage)
- 支持与认证系统组合使用
- 添加中英文文档
- 导出路径: @esengine/server/ratelimit

* docs: 更新 README 添加新模块 | update README with new modules

- 添加程序化生成 (procgen) 模块
- 添加 RPC 框架模块
- 添加游戏服务器 (server) 模块
- 添加事务系统 (transaction) 模块
- 添加世界流送 (world-streaming) 模块
- 更新网络模块描述
- 更新项目结构目录
 2025-12-29 17:12:54 +08:00
YHH
61a13baca2 feat(server): 添加可插拔认证系统 | add pluggable authentication system (#386) 
* feat(server): 添加可插拔认证系统 | add pluggable authentication system

- 新增 JWT 认证提供者 (createJwtAuthProvider)
- 新增 Session 认证提供者 (createSessionAuthProvider)
- 新增服务器认证 mixin (withAuth)
- 新增房间认证 mixin (withRoomAuth)
- 新增认证装饰器 (@requireAuth, @requireRole)
- 新增测试工具 (MockAuthProvider)
- 新增中英文文档
- 导出路径: @esengine/server/auth, @esengine/server/auth/testing

* fix(server): 使用加密安全的随机数生成 session ID | use crypto-secure random for session ID
 2025-12-29 16:10:09 +08:00
YHH
3b978384c7 feat(framework): server testing utils, transaction storage simplify, pathfinding tests (#384) 
## Server Testing Utils
- Add TestServer, TestClient, MockRoom for unit testing
- Export testing utilities from @esengine/server/testing

## Transaction Storage (BREAKING)
- Simplify RedisStorage/MongoStorage to factory pattern only
- Remove DI client injection option
- Add lazy connection and Symbol.asyncDispose support
- Add 161 unit tests with full coverage

## Pathfinding Tests
- Add 150 unit tests covering all components
- BinaryHeap, Heuristics, AStarPathfinder, GridMap, NavMesh, PathSmoother

## Docs
- Update storage.md for new factory pattern API
 2025-12-29 15:02:13 +08:00
YHH
10c3891abd docs: 添加缺失的侧边栏导航项 | add missing sidebar items (#383) 
- RPC: 添加 server, client, codec 页面
- Network: 添加 prediction, aoi, delta 页面
- Transaction: 添加完整模块导航
- Changelog: 添加 transaction, rpc 链接
 2025-12-29 11:29:42 +08:00
YHH
d4cef828e1 feat(transaction): 添加游戏事务系统 | add game transaction system (#381) 
- TransactionManager/TransactionContext 事务管理
- MemoryStorage/RedisStorage/MongoStorage 存储实现
- CurrencyOperation/InventoryOperation/TradeOperation 内置操作
- SagaOrchestrator 分布式 Saga 编排
- withTransactions() Room 集成
- 完整中英文文档
 2025-12-29 10:54:00 +08:00
YHH
fb8bde6485 feat(network): 网络模块增强 - 预测、AOI、增量压缩 (#379) 
- 添加 NetworkPredictionSystem 客户端预测系统
- 添加 NetworkAOISystem 兴趣区域管理
- 添加 StateDeltaCompressor 状态增量压缩
- 添加断线重连和状态恢复
- 增强协议支持时间戳、序列号、速度
- 添加中英文文档
 2025-12-29 10:42:48 +08:00
yhh
30437dc5d5 docs: add world-streaming to sidebar navigation 2025-12-28 19:50:44 +08:00
YHH
0662b07445 chore: update pathfinding, add rpc/world-streaming docs, refactor world-streaming location (#376) 2025-12-28 19:18:28 +08:00
YHH
b6f1235239 feat(server): 添加游戏服务器框架 | add game server framework (#366) 
**@esengine/server** - 游戏服务器框架 | Game server framework
- 文件路由系统 | File-based routing
- Room 生命周期 (onCreate, onJoin, onLeave, onTick, onDispose)
- @onMessage 装饰器 | Message handler decorator
- 玩家管理与断线处理 | Player management with auto-disconnect
- 内置 JoinRoom/LeaveRoom API | Built-in room APIs
- defineApi/defineMsg 类型安全辅助函数 | Type-safe helpers

**create-esengine-server** - CLI 脚手架工具 | CLI scaffolding
- 生成 shared/server/client 项目结构 | Project structure
- 类型安全的协议定义 | Type-safe protocol definitions
- 包含 GameRoom 示例 | Example implementation

**其他 | Other**
- 删除旧的 network-server 包 | Remove old network-server
- 更新服务器文档 | Update server documentation
 2025-12-28 12:23:55 +08:00
YHH
7940f581a6 feat(rpc,network): 新增 RPC 库并迁移网络模块 (#364) 
* feat(rpc,network): 新增 RPC 库并迁移网络模块

## @esengine/rpc (新增)
- 新增类型安全的 RPC 库，支持 WebSocket 通信
- 新增 RpcClient 类：connect/disconnect, call/send/on/off/once 方法
- 新增 RpcServer 类：Node.js WebSocket 服务端
- 新增编解码系统：支持 JSON 和 MessagePack
- 新增 TextEncoder/TextDecoder polyfill，兼容微信小游戏平台
- 新增 WebSocketAdapter 接口，支持跨平台 WebSocket 抽象

## @esengine/network (重构)
- 重构 NetworkService：拆分为 RpcService 基类和 GameNetworkService
- 新增 gameProtocol：类型安全的 API 和消息定义
- 新增类型安全便捷方法：sendInput(), onSync(), onSpawn(), onDespawn()
- 更新 NetworkPlugin 使用新的服务架构
- 移除 TSRPC 依赖，改用 @esengine/rpc

## 文档
- 新增 RPC 模块文档（中英文）
- 更新 Network 模块文档（中英文）
- 更新侧边栏导航

* fix(network,cli): 修复 CI 构建和更新 CLI 适配器

## 修复
- 在 tsconfig.build.json 添加 rpc 引用，修复类型声明生成

## CLI 更新
- 更新 nodejs 适配器使用新的 @esengine/rpc
- 生成的服务器代码使用 RpcServer 替代旧的 GameServer
- 添加 ws 和 @types/ws 依赖
- 更新 README 模板中的客户端连接示例

* chore: 添加 CLI changeset

* fix(ci): add @esengine/rpc to build and check scripts

- Add rpc package to CI build step (must build before network)
- Add rpc to type-check:framework, lint:framework, test:ci:framework

* fix(rpc,network): fix tsconfig for declaration generation

- Remove composite mode from rpc (not needed, causes CI issues)
- Remove rpc from network project references (resolves via node_modules)
- Remove unused references from network tsconfig.build.json
 2025-12-28 10:54:51 +08:00
YHH
8605888f11 docs: restructure documentation with modular sub-pages (#363) 
* docs: split Entity docs into sub-modules and fix Starlight CI

- Split monolithic entity.md into 4 focused sub-documents:
  - guide/entity/index.md - Overview and basic concepts
  - guide/entity/component-operations.md - Component API operations
  - guide/entity/entity-handle.md - EntityHandle system for safe references
  - guide/entity/lifecycle.md - Lifecycle and persistence management

- Created bilingual versions (Chinese and English)

- Updated sidebar configuration in astro.config.mjs

- Fixed CI workflow for Starlight migration:
  - Updated docs.yml to upload from docs/dist instead of .vitepress/dist
  - Updated package.json scripts to use pnpm filter for docs
  - Added docs directory to pnpm-workspace.yaml
  - Renamed docs package to @esengine/docs

- Documented missing Entity APIs:
  - createComponent() method
  - addComponents() batch method
  - getComponentByType() with inheritance support
  - markDirty() for change detection

* docs: split Network docs and fix API errors

- Split network module into focused sub-documents:
  - modules/network/index.md - Overview and quick start
  - modules/network/client.md - Client-side usage
  - modules/network/server.md - Server-side GameServer/Room
  - modules/network/sync.md - Interpolation and prediction
  - modules/network/api.md - Complete API reference

- Fixed incorrect API documentation:
  - localClientId → clientId
  - ENetworkState enum values (strings → numbers)
  - connect() method signature
  - Removed non-existent localPlayerId property
  - Fixed onConnected callback signature

- Created bilingual versions (Chinese and English)
- Updated sidebar configuration
- Updated pnpm-lock.yaml for docs workspace

* docs(worker-system): split into focused sub-modules

Split 773-line worker-system.md into 5 focused documents:
- index.md: Core features and quick start
- configuration.md: IWorkerSystemConfig and processing modes
- examples.md: Complete particle physics implementation
- wechat.md: WeChat Mini Game limitations and solutions
- best-practices.md: Performance optimization tips

Updated sidebar config to reflect new structure.
Created both Chinese and English versions.

* docs(scene): split into focused sub-modules

Split 666-line scene.md into 7 focused documents:
- index.md: Overview and quick start
- lifecycle.md: Scene lifecycle methods
- entity-management.md: Entity creation, find, destroy
- system-management.md: System add, remove, control
- events.md: Event system usage
- debugging.md: Stats, performance monitoring
- best-practices.md: Design patterns and examples

Updated sidebar config to reflect new structure.
Created both Chinese and English versions.

* docs(plugin-system): split into focused sub-modules

Split 645-line plugin-system.md into 7 focused documents:
- index.md: Overview and quick start
- development.md: IPlugin interface and lifecycle
- services-systems.md: Register services and add systems
- dependencies.md: Dependency management
- management.md: Plugin management via Core/PluginManager
- examples.md: Complete plugin examples
- best-practices.md: Design guidelines and FAQ

Updated sidebar config to reflect new structure.
Created both Chinese and English versions.

* docs(behavior-tree): add English docs and expand sidebar navigation

- Add 12 English behavior-tree documentation pages
- Update sidebar config to show behavior-tree sub-navigation
- Include: overview, getting-started, core-concepts, custom-actions,
  editor-guide, editor-workflow, asset-management, advanced-usage,
  best-practices, cocos-integration, laya-integration, nodejs-usage

* docs(modules): split spatial and timer module docs

Spatial module (602 lines -> 5 files):
- index.md: Overview and quick start
- spatial-index.md: Grid index, range queries, raycasting API
- aoi.md: Area of Interest management
- examples.md: Combat, MMO sync, AI perception examples
- utilities.md: Geometry detection, performance tips

Timer module (481 lines -> 4 files):
- index.md: Overview and core concepts
- api.md: Complete timer and cooldown API
- examples.md: Skill cooldowns, DOT, buff systems
- best-practices.md: Usage tips, ECS integration

Also includes English versions and sidebar navigation updates.

* docs: split FSM, pathfinding, blueprint, procgen module docs

- FSM: Split into index, api, examples (3 files)
- Pathfinding: Split into index, grid-map, navmesh, smoothing, examples (5 files)
- Blueprint: Split into index, vm, custom-nodes, nodes, composition, examples (6 files)
- Procgen: Split into index, noise, random, sampling, examples (5 files)
- Added English versions for all split modules
- Updated sidebar navigation with sub-menus for all modules
 2025-12-27 20:35:54 +08:00
YHH
d57a007a42 docs: split Entity docs into sub-modules and fix Starlight CI (#362) 
* docs: split Entity docs into sub-modules and fix Starlight CI

- Split monolithic entity.md into 4 focused sub-documents:
  - guide/entity/index.md - Overview and basic concepts
  - guide/entity/component-operations.md - Component API operations
  - guide/entity/entity-handle.md - EntityHandle system for safe references
  - guide/entity/lifecycle.md - Lifecycle and persistence management

- Created bilingual versions (Chinese and English)

- Updated sidebar configuration in astro.config.mjs

- Fixed CI workflow for Starlight migration:
  - Updated docs.yml to upload from docs/dist instead of .vitepress/dist
  - Updated package.json scripts to use pnpm filter for docs
  - Added docs directory to pnpm-workspace.yaml
  - Renamed docs package to @esengine/docs

- Documented missing Entity APIs:
  - createComponent() method
  - addComponents() batch method
  - getComponentByType() with inheritance support
  - markDirty() for change detection

* docs: split Network docs and fix API errors

- Split network module into focused sub-documents:
  - modules/network/index.md - Overview and quick start
  - modules/network/client.md - Client-side usage
  - modules/network/server.md - Server-side GameServer/Room
  - modules/network/sync.md - Interpolation and prediction
  - modules/network/api.md - Complete API reference

- Fixed incorrect API documentation:
  - localClientId → clientId
  - ENetworkState enum values (strings → numbers)
  - connect() method signature
  - Removed non-existent localPlayerId property
  - Fixed onConnected callback signature

- Created bilingual versions (Chinese and English)
- Updated sidebar configuration
- Updated pnpm-lock.yaml for docs workspace
 2025-12-27 13:28:49 +08:00
YHH
89cdfe396b docs: migrate documentation from VitePress to Starlight (#361) 
- Replace VitePress with Astro Starlight for documentation
- Reorganize document structure with better hierarchy
- Split large documents into sub-modules for better readability
- Add new sections: component, entity-query, serialization, system
- Support both Chinese (default) and English documentation
- Add responsive design and improved navigation
 2025-12-27 12:54:53 +08:00
YHH
1e240e86f2 feat(cli): 增强 Node.js 服务端适配器 (#354) 
* docs(network): 添加网络模块文档和 CLI 支持

- 添加中英文网络模块文档
- 将 network、network-protocols、network-server 加入 CLI 模块列表

* feat(cli): 增强 Node.js 服务端适配器

- 添加 @esengine/network-server 依赖支持
- 生成完整的 ECS 游戏服务器项目结构
- 修复 network-server 包支持 ESM/CJS 双格式
- 添加 ws@8.18.0 解决 Node.js 24 兼容性问题
- 组件使用 @ECSComponent 装饰器注册
- tsconfig 启用 experimentalDecorators
 2025-12-27 00:13:58 +08:00
YHH
33e98b9a75 fix(cli): 修复 Cocos Creator 3.x 项目检测逻辑 (#352) 
* docs(network): 添加网络模块文档和 CLI 支持

- 添加中英文网络模块文档
- 将 network、network-protocols、network-server 加入 CLI 模块列表

* fix(cli): 修复 Cocos Creator 3.x 项目检测逻辑

- 重构检测代码，提取通用辅助函数
- 优先检查 package.json 中的 creator.version 字段
- 添加 .creator 和 settings 目录检测
- 使用 getMajorVersion 统一版本号解析

* chore: add changeset
 2025-12-26 23:14:23 +08:00
YHH
4a16e30794 docs(modules): 添加框架模块文档 (#350) 
* docs(modules): 添加框架模块文档

添加以下模块的完整文档：
- FSM (状态机): 状态定义、转换条件、优先级、事件监听
- Timer (定时器): 定时器调度、冷却系统、服务令牌
- Spatial (空间索引): GridSpatialIndex、AOI 兴趣区域管理
- Pathfinding (寻路): A* 算法、网格地图、导航网格、路径平滑
- Procgen (程序化生成): 噪声函数、种子随机数、加权随机

所有文档均基于实际源码 API 编写，包含：
- 快速开始示例
- 完整 API 参考
- 实际使用案例
- 蓝图节点说明
- 最佳实践建议

* docs(modules): 添加 Blueprint 模块文档和所有模块英文版

新增中文文档：
- Blueprint (蓝图可视化脚本): VM、自定义节点、组合系统、触发器

新增英文文档 (docs/en/modules/):
- FSM: State machine API, transitions, ECS integration
- Timer: Timers, cooldowns, service tokens
- Spatial: Grid spatial index, AOI management
- Pathfinding: A*, grid map, NavMesh, path smoothing
- Procgen: Noise functions, seeded random, weighted random
- Blueprint: Visual scripting, custom nodes, composition

所有文档均基于实际源码 API 编写。
 2025-12-26 20:02:21 +08:00
YHH
76691cc198 docs: 重构文档结构，添加独立模块区域 (#349) 
* docs: 重构文档结构，添加独立模块区域

- 新增 /modules/ 目录用于功能模块文档
- 移动 behavior-tree 从 /guide/ 到 /modules/
- 添加模块总览页面
- 更新导航栏添加"模块"入口
- 更新侧边栏：模块区域独立侧边栏
- 更新 i18n 配置支持新模块

* style(docs): 提高文字对比度
 2025-12-26 19:15:08 +08:00
YHH
ede440d277 chore: changeset for framework package configs (#347) 
* chore: add changeset for framework package configs

* fix(docs): 修复 VitePress 配置中的包路径
 2025-12-26 18:13:12 +08:00
YHH
31fd34b221 fix: update Laya examples, add CLI docs, fix changesets workflow (#340) 
* fix: update Laya examples, add CLI docs, fix changesets workflow

- Update Laya examples to use Laya 3.x Script pattern (@regClass)
- Add CLI tool quick start section to README (npx @esengine/cli init)
- Fix changesets workflow to only build framework packages
- Remove unnecessary Rust/WASM build steps from changesets workflow
- Remove redundant 'pnpm build' from changeset:publish script

* docs: add CLI documentation and update Laya examples

- Add CLI quick start section to getting-started.md (zh/en)
- Update Laya examples to use Laya 3.x Script pattern
 2025-12-26 16:37:37 +08:00
yhh
5544fca002 docs: update changelog for v2.4.2 2025-12-25 20:42:15 +08:00
yhh
49dd6a91c6 docs: v2.4.1 changelog 2025-12-23 15:22:33 +08:00
yhh
dff2ec564b fix(core): IntervalSystem时间累加bug修复 & 添加Core.paused文档 
- 修复 onCheckProcessing() 在 update/lateUpdate 被调用两次导致时间累加翻倍的问题
- 添加 Core.paused 游戏暂停文档（中/英文）
- 新增 IntervalSystem 相关测试用例
 2025-12-23 09:41:22 +08:00
YHH
536c4c5593 refactor(ui): UI 系统架构重构 (#309) 
* feat(ui): 动态图集系统与渲染调试增强

## 核心功能

### 动态图集系统 (Dynamic Atlas)
- 新增 DynamicAtlasManager：运行时纹理打包，支持 MaxRects 算法
- 新增 DynamicAtlasService：自动纹理加载与图集管理
- 新增 BinPacker：高效矩形打包算法
- 支持动态/固定两种扩展策略
- 自动 UV 重映射，实现 UI 元素合批渲染

### Frame Debugger 增强
- 新增合批分析面板，显示批次中断原因
- 新增 UI 元素层级信息（depth, worldOrderInLayer）
- 新增实体高亮功能，点击可在场景中定位
- 新增动态图集可视化面板
- 改进渲染原语详情展示

### 闪光效果 (Shiny Effect)
- 新增 UIShinyEffectComponent：UI 闪光参数配置
- 新增 UIShinyEffectSystem：材质覆盖驱动的闪光动画
- 新增 ShinyEffectComponent/System（Sprite 版本）

## 引擎层改进

### Rust 纹理管理扩展
- create_blank_texture：创建空白 GPU 纹理
- update_texture_region：局部纹理更新
- 支持动态图集的 GPU 端操作

### 材质系统
- 新增 effects/ 目录：ShinyEffect 等效果实现
- 新增 interfaces/ 目录：IMaterial 等接口定义
- 新增 mixins/ 目录：可组合的材质功能

### EngineBridge 扩展
- 新增 createBlankTexture/updateTextureRegion 方法
- 改进纹理加载回调机制

## UI 渲染改进
- UIRenderCollector：支持合批调试信息
- 稳定排序：addIndex 保证渲染顺序一致性
- 九宫格渲染优化
- 材质覆盖支持

## 其他改进
- 国际化：新增 Frame Debugger 相关翻译
- 编辑器：新增渲染调试入口
- 文档：新增架构设计文档目录

* refactor(ui): 引入新基础组件架构与渲染工具函数

Phase 1 重构 - 组件职责分离与代码复用：

新增基础组件层：
- UIGraphicComponent: 所有可视 UI 元素的基类（颜色、透明度、raycast）
- UIImageComponent: 纹理显示组件（支持简单、切片、平铺、填充模式）
- UISelectableComponent: 可交互元素的基类（状态管理、颜色过渡）

新增渲染工具：
- UIRenderUtils: 提取共享的坐标计算、边框渲染、阴影渲染等工具函数
- getUIRenderTransform: 统一的变换数据提取
- renderBorder/renderShadow: 复用的边框和阴影渲染逻辑

新增渲染系统：
- UIGraphicRenderSystem: 处理新基础组件的统一渲染器

重构现有系统：
- UIRectRenderSystem: 使用新工具函数，移除重复代码
- UIButtonRenderSystem: 使用新工具函数，移除重复代码

这些改动为后续统一渲染系统奠定基础。

* refactor(ui): UIProgressBarRenderSystem 使用渲染工具函数

- 使用 getUIRenderTransform 替代手动变换计算
- 使用 renderBorder 工具函数替代重复的边框渲染
- 使用 lerpColor 工具函数替代重复的颜色插值
- 简化方法签名，使用 UIRenderTransform 类型
- 移除约 135 行重复代码

* refactor(ui): Slider 和 ScrollView 渲染系统使用工具函数

- UISliderRenderSystem: 使用 getUIRenderTransform，简化方法签名
- UIScrollViewRenderSystem: 使用 getUIRenderTransform，简化方法签名
- 统一使用 UIRenderTransform 类型减少参数传递
- 消除重复的变换计算代码

* refactor(ui): 使用 UIWidgetMarker 消除硬编码组件依赖

- 新增 UIWidgetMarker 标记组件
- UIRectRenderSystem 改为检查标记而非硬编码4种组件类型
- 各 Widget 渲染系统自动添加标记组件
- 减少模块间耦合，提高可扩展性

* feat(ui): 实现 Canvas 隔离机制

- 新增 UICanvasComponent 定义 Canvas 渲染组
- UITransformComponent 添加 Canvas 相关字段：canvasEntityId, worldSortingLayer, pixelPerfect
- UILayoutSystem 传播 Canvas 设置给子元素
- UIRenderUtils 使用 Canvas 继承的排序层
- 支持嵌套 Canvas 和不同渲染模式

* refactor(ui): 统一纹理管理工具函数

Phase 4: 纹理管理统一

新增:
- UITextureUtils.ts: 统一的纹理描述符接口和验证函数
  - UITextureDescriptor: 支持 GUID/textureId/path 多种纹理源
  - isValidTextureGuid: GUID 验证
  - getTextureKey: 获取用于合批的纹理键
  - normalizeTextureDescriptor: 规范化各种输入格式
- utils/index.ts: 工具函数导出

修改:
- UIGraphicRenderSystem: 使用新的纹理工具函数
- index.ts: 导出纹理工具类型和函数

* refactor(ui): 实现统一的脏标记机制

Phase 5: Dirty 标记机制

新增:
- UIDirtyFlags.ts: 位标记枚举和追踪工具
  - UIDirtyFlags: Visual/Layout/Transform/Material/Text 标记
  - IDirtyTrackable: 脏追踪接口
  - DirtyTracker: 辅助工具类
  - 帧级别脏状态追踪 (markFrameDirty, isFrameDirty)

修改:
- UIGraphicComponent: 实现 IDirtyTrackable
  - 属性 setter 自动设置脏标记
  - 保留 setDirty/clearDirty 向后兼容
- UIImageComponent: 所有属性支持脏追踪
  - textureGuid/imageType/fillAmount 等变化自动标记
- UIGraphicRenderSystem: 使用 clearDirtyFlags()

导出:
- UIDirtyFlags, IDirtyTrackable, DirtyTracker
- markFrameDirty, isFrameDirty, clearFrameDirty

* refactor(ui): 移除过时的 dirty flag API

移除 UIGraphicComponent 中的兼容性 API:
- 移除 _isDirty getter/setter
- 移除 setDirty() 方法
- 移除 clearDirty() 方法

现在统一使用新的 dirty flag 系统:
- isDirty() / hasDirtyFlag(flags)
- markDirty(flags) / clearDirtyFlags()

* fix(ui): 修复两个 TODO 功能

1. 滑块手柄命中测试 (UIInputSystem)
   - UISliderComponent 添加 getHandleBounds() 计算手柄边界
   - UISliderComponent 添加 isPointInHandle() 精确命中测试
   - UIInputSystem.handleSlider() 使用精确测试更新悬停状态

2. 径向填充渲染 (UIGraphicRenderSystem)
   - 实现 renderRadialFill() 方法
   - 支持 radial90/radial180/radial360 三种模式
   - 支持 fillOrigin (top/right/bottom/left) 和 fillClockwise
   - 使用多段矩形近似饼形填充效果

* feat(ui): 完善 UI 系统架构和九宫格渲染

* fix(ui): 修复文本渲染层级问题并清理调试代码

- 修复纹理就绪后调用 invalidateUIRenderCaches() 导致的无限循环
- 移除 UITextRenderSystem、UIButtonRenderSystem、UIRectRenderSystem 中的首帧调试输出
- 移除 UILayoutSystem 中的布局调试日志
- 清理所有 __UI_RENDER_DEBUG__ 条件日志

* refactor(ui): 优化渲染批处理和输入框组件

渲染系统:
- 修复 RenderBatcher 保持渲染顺序
- 优化 Rust SpriteBatch 避免合并非连续精灵
- 增强 EngineRenderSystem 纹理就绪检测

输入框组件:
- 增强 UIInputFieldComponent 功能
- 改进 UIInputSystem 输入处理
- 新增 TextMeasureService 文本测量服务

* fix(ui): 修复九宫格首帧渲染和InputField输入问题

- 修复九宫格首帧 size=0x0 问题：
  - Viewport.tsx: 预览模式读取图片尺寸存储到 importSettings
  - AssetDatabase: ISpriteSettings 添加 width/height 字段
  - AssetMetadataService: getTextureSpriteInfo 使用元数据尺寸作为后备
  - UIRectRenderSystem: 当 atlasEntry 不存在时使用 spriteInfo 尺寸
  - WebBuildPipeline: 构建时包含 importSettings
  - AssetManager: 从 catalog 初始化时复制 importSettings
  - AssetTypes: IAssetCatalogEntry 添加 importSettings 字段

- 修复 InputField 无法输入问题：
  - UIRuntimeModule: manifest 添加 pluginExport: 'UIPlugin'
  - 确保预览模式正确加载 UI 插件并绑定 UIInputSystem

- 添加调试日志用于排查纹理加载问题

* fix(sprite): 修复类型导出错误

MaterialPropertyOverride 和 MaterialOverrides 应从 @esengine/material-system 导出

* fix(ui-editor): 补充 AnchorPreset 拉伸预设的映射

添加 StretchTop, StretchMiddle, StretchBottom, StretchLeft, StretchCenter, StretchRight 的位置和锚点值映射
 2025-12-19 15:33:36 +08:00
yhh
85e95ec18c docs: add English entity documentation with EntityHandle 2025-12-15 10:00:44 +08:00
yhh
ff9bc00729 docs: 改进 EntityHandle 文档，添加实际使用场景示例 2025-12-15 09:59:12 +08:00
yhh
7451a78e60 docs: 补充 EntityHandle 实体句柄文档 2025-12-15 09:38:45 +08:00
yhh
23ee2393c6 chore(release): 准备发布 v2.4.0，改进 CI 发布流程 
- 更新 @esengine/ecs-framework 版本号到 2.4.0
- 更新中英文 changelog
- CI: 支持标签触发自动发布（v* 或 package-v* 格式）
- CI: 保留手动触发选项
- CI: 标签模式下自动创建 GitHub Release
 2025-12-15 09:33:51 +08:00
YHH
cd6ef222d1 feat(ecs): 核心系统改进 - 句柄、调度、变更检测与查询编译 (#304) 
新增功能:
- EntityHandle: 轻量级实体句柄 (28位索引 + 20位代数)
- SystemScheduler: 声明式系统调度，支持 @Stage/@Before/@After/@InSet 装饰器
- EpochManager: 帧级变更检测
- CompiledQuery: 预编译类型安全查询

API 改进:
- EntitySystem 添加 getBefore()/getAfter()/getSets() getter 方法
- Entity 添加 markDirty() 辅助方法
- IScene 添加 epochManager 属性
- CommandBuffer.pendingCount 修正为返回实际操作数

文档更新:
- 更新系统调度和查询相关文档
 2025-12-15 09:17:00 +08:00
yhh
b5158b6ac6 chore: 移除第三方引擎引用，改进 README 专业度 2025-12-13 20:56:22 +08:00
yhh
40a38b8b88 docs: 更新品牌形象和项目文档 
- 新增 ES logo (docs/public/logo.svg)
- README 添加居中 logo、徽章和导航链接
- 更新 LICENSE 版权为 ESEngine Contributors
- SECURITY.md 添加英文版本，更新联系方式
- 移除不稳定的性能测试
 2025-12-08 21:47:47 +08:00
yhh
ad96edfad0 fix: 恢复 @esengine/ecs-framework 包名 
上一个提交错误地将 npm 包名也改了，这里恢复正确的包名。
只更新 GitHub 仓库 URL，不改变 npm 包名。
 2025-12-08 21:26:35 +08:00
yhh
240b165970 chore: 更新仓库 URL (ecs-framework → esengine) 
仓库已从 esengine/ecs-framework 重命名为 esengine/esengine
更新所有引用旧 URL 的文件
 2025-12-08 21:23:37 +08:00
yhh
2476379af1 docs: 更新 worker-generator 版本号为 v1.0.2 2025-12-08 18:34:49 +08:00
yhh
9ff03c04f3 docs: 更新 worker-generator 版本号为 v1.0.1 2025-12-08 17:17:26 +08:00
yhh
a733a53d3e chore(release): 准备发布 v2.3.2 和 worker-generator v1.0.0 
- 更新 @esengine/ecs-framework 版本号到 2.3.2
- 更新中英文 changelog
 2025-12-08 17:04:01 +08:00
YHH
dfd0dfc7f9 feat(worker): 添加微信小游戏 Worker 支持和 Worker Generator CLI (#297) 
* feat(worker): 添加微信小游戏 Worker 支持和 Worker Generator CLI

- 新增 @esengine/worker-generator 包，用于从 WorkerEntitySystem 生成 Worker 文件
- WorkerEntitySystem 添加 workerScriptPath 配置项，支持预编译 Worker 脚本
- CLI 工具支持 --wechat 模式，自动转换 ES6+ 为 ES5 语法
- 修复微信小游戏 Worker 消息格式差异（res 直接是数据，无需 .data）
- 更新中英文文档，添加微信小游戏支持章节

* docs: 更新 changelog，添加 v2.3.1 说明并标注 v2.3.0 为废弃

* fix: 修复 CI 检查问题

- 移除 cli.ts 中未使用的 toKebabCase 函数
- 修复 generator.ts 中正则表达式的 ReDoS 风险（使用 [ \t] 替代 \s*）
- 更新 changelog 版本号（2.3.1 -> 2.3.2）

* docs: 移除未发布版本的 changelog 条目

* fix(worker-generator): 使用 TypeScript 编译器替代手写正则进行 ES5 转换

- 修复 CodeQL 检测的 ReDoS 安全问题
- 使用 ts.transpileModule 进行安全可靠的代码转换
- 移除所有可能导致回溯的正则表达式
 2025-12-08 17:02:11 +08:00