feat(spx_tilemap_exporter): add Python export script and documentation

addons/spx_tilemap_exporter/README.md

@@ -0,0 +1,189 @@
+# SPX TileMap Exporter
+
+A Godot editor plugin for exporting TileMap scenes and decorators to SPX JSON format for dynamic loading in the SPX runtime.
+
+## Quick Start
+
+```bash
+# 1. Copy the plugin to your project's addons directory
+cp -r spx_tilemap_exporter /path/to/your/project/addons/
+
+# 2. Navigate to your project directory
+cd /path/to/your/project
+
+# 3. Export the scene
+python addons/spx_tilemap_exporter/export.py --godot /path/to/godot --scene main.tscn
+
+# Export files are saved in the `res://_export/<scene_name>/` directory
+```
+
+## Features
+
+- **TileMap Export**: Export TileMapLayer, TileSet, and physics collision data
+- **Decorator Export**: Export Sprite2D nodes and prefab instances from scenes
+- **Automatic Texture Copy**: Automatically copy related textures to the export directory
+- **Coordinate System Conversion**: Automatically convert Godot coordinates to SPX coordinates (Y-axis flip)
+- **Collision Shape Support**: Support for exporting rectangle, circle, capsule, and polygon colliders
+- **CLI Support**: Provides CLI scripts for batch automation exports
+
+## Installation
+
+1. Copy the `spx_tilemap_exporter` folder to the `addons/` directory of the Godot project you want to export
+
+> **Note**: If you only use command-line export, the above steps complete the installation.
+> To use the editor menu export feature, you also need to enable the "SPX TileMap Exporter" plugin in the Godot editor under **Project > Project Settings > Plugins**.
+
+## Usage
+
+### Command Line Export (Recommended)
+
+Using the Python script for export is the simplest method:
+
+**Method 1: Specify Godot path via command line argument**
+
+```bash
+python export.py --godot /path/to/godot --scene levels/level1.tscn
+```
+
+**Method 2: Specify Godot path via environment variable**
+
+```bash
+# Linux/macOS
+export GODOT_PATH=/path/to/godot
+
+# Windows
+set GODOT_PATH=C:\path\to\godot.exe
+
+# Export a specific scene
+python export.py --scene levels/level1.tscn
+```
+
+**Godot Path Priority:**
+1. `--godot` command line argument (highest priority)
+2. `GODOT_PATH` environment variable
+3. If neither is specified, an error message will be displayed
+
+**Parameters:**
+
+| Parameter | Description |
+|-----------|-------------|
+| `--godot PATH` | Specify the Godot executable path (takes priority over environment variable) |
+| `--scene PATH` | Specify the scene file path to export, `res://` prefix is optional (default: `res://main.tscn`) |
+
+
+### Editor Menu Export
+
+> **Prerequisite**: You need to enable the plugin in the Godot editor first (**Project > Project Settings > Plugins**)
+
+After enabling the plugin, you can access export features through the **Project > Tools** menu:
+
+| Menu Item | Function |
+|-----------|----------|
+| **SPX Export TileMap...** | Export only the TileMap data from the current scene |
+| **SPX Export Decorators...** | Export only the decorator data from the current scene |
+| **SPX Export All...** | Export both TileMap and decorator data |
+
+
+### Direct Godot CLI Usage
+
+For more granular control, you can use the Godot command line directly:
+
+```bash
+# Basic usage (exports default scene res://main.tscn)
+godot --headless --path <project_path> -s addons/spx_tilemap_exporter/export_cli.gd
+
+# Export a specific scene
+godot --headless --path <project_path> -s addons/spx_tilemap_exporter/export_cli.gd -- --scene res://levels/level1.tscn
+```
+
+| Parameter | Description |
+|-----------|-------------|
+| `--scene <path>` | Specify the scene path to export (must be placed after `--`) |
+
+## Export Output
+
+Export files are saved in the `res://_export/<scene_name>/` directory:
+
+```
+_export/
+└── <scene_name>/
+    ├── tilemap.json        # TileMap data
+    ├── tilemap/            # TileMap texture directory
+    │   └── *.png
+    ├── decorator.json      # Decorator data
+    └── decorator/          # Decorator texture directory
+        └── *.png
+```
+
+## Configuration
+
+### CLI Script Configuration
+
+Edit the constants in `export_cli.gd` to modify the default configuration:
+
+```gdscript
+const DEFAULT_SCENE_PATH = "res://main.tscn"  # Default scene path to export
+const EXPORT_TILEMAP = true                   # Whether to export TileMap
+const EXPORT_DECORATORS = true                # Whether to export decorators
+```
+
+### Excluding Nodes
+
+The following nodes are automatically excluded during decorator export:
+
+- Nodes belonging to the `spx_ignore` group
+- TileMapLayer and TileMap nodes (exported separately)
+- Nodes with names containing `_ignore` or `_skip`
+
+## File Descriptions
+
+| File | Description |
+|------|-------------|
+| `plugin.cfg` | Plugin configuration file |
+| `spx_tilemap_exporter.gd` | Main plugin script, provides editor menu functionality |
+| `tilemap_extractor.gd` | TileMap data extraction and export logic |
+| `decorator_extractor.gd` | Decorator data extraction and export logic |
+| `export_cli.gd` | Command-line export script (Godot --headless mode) |
+| `export.py` | Python automation export script |
+
+
+## Requirements
+
+- Godot 4.x
+- Python 3.8+ (when using the Python export script)
+
+---
+
+## For Engine Developers
+
+> The following content is for SPX engine developers only. Regular users can skip this section.
+
+### Plugin Rapid Iteration
+
+When developing the `spx_tilemap_exporter` plugin, you can use the `--copy` parameter to copy the latest plugin code from the engine source directory to the target project:
+
+```bash
+# Export with addon copy (copy latest plugin from source to project directory)
+python export.py --copy
+
+# Combined usage: copy plugin and export a specific scene
+python export.py --copy --scene my_scene.tscn
+
+# Combined usage: specify Godot path, copy plugin, and export a specific scene
+python export.py --godot /path/to/godot --copy --scene my_scene.tscn
+```
+
+| Parameter | Description |
+|-----------|-------------|
+| `--godot PATH` | Specify the Godot executable path (takes priority over `GODOT_PATH` environment variable) |
+| `--copy` | Copy the latest plugin from `pkg/gdspx/godot/addons/` to the current project directory for rapid plugin development iteration |
+
+**Workflow:**
+
+1. Modify the plugin code in `pkg/gdspx/godot/addons/spx_tilemap_exporter/`
+2. Navigate to the test project directory (e.g., `tutorial/AA-00Town/`)
+3. Run `python export.py --copy` to automatically copy the plugin and test the export
+
+## License
+
+SPX Team © 2026

addons/spx_tilemap_exporter/README.zh.md

@@ -0,0 +1,189 @@
+# SPX TileMap Exporter
+
+Godot 编辑器插件，用于将 TileMap 场景和装饰器导出为 SPX JSON 格式，以便在 SPX 运行时动态加载。
+
+## 快速开始
+
+```bash
+# 1. 将插件复制到项目的 addons 目录
+cp -r spx_tilemap_exporter /path/to/your/project/addons/
+
+# 2. 进入项目目录
+cd /path/to/your/project
+
+# 3. 导出场景
+python addons/spx_tilemap_exporter/export.py --godot /path/to/godot --scene main.tscn
+
+# 导出文件保存在 `res://_export/<场景名>/` 目录：
+```
+
+## 功能特性
+
+- **TileMap 导出**：导出 TileMapLayer、TileSet 及物理碰撞数据
+- **装饰器导出**：导出场景中的 Sprite2D 节点和预制体实例
+- **纹理自动复制**：自动将相关纹理复制到导出目录
+- **坐标系转换**：自动将 Godot 坐标系转换为 SPX 坐标系（Y 轴翻转）
+- **碰撞形状支持**：支持导出矩形、圆形、胶囊体和多边形碰撞器
+- **命令行支持**：提供 CLI 脚本用于批量自动化导出
+
+## 安装
+
+1. 将 `spx_tilemap_exporter` 文件夹复制到需要导出的 Godot 项目的 `addons/` 目录
+
+> **注意**：如果只使用命令行导出，以上步骤即可完成安装。
+> 如需使用编辑器菜单导出功能，还需在 Godot 编辑器中 **项目 > 项目设置 > 插件** 启用 "SPX TileMap Exporter" 插件。
+
+## 使用方法
+
+### 命令行导出（推荐）
+
+使用 Python 脚本进行导出是最简单的方式：
+
+**方式一：通过命令行参数指定 Godot 路径**
+
+```bash
+python export.py --godot /path/to/godot --scene levels/level1.tscn
+```
+
+**方式二：通过环境变量指定 Godot 路径**
+
+```bash
+# Linux/macOS
+export GODOT_PATH=/path/to/godot
+
+# Windows
+set GODOT_PATH=C:\path\to\godot.exe
+
+# 导出指定场景
+python export.py --scene levels/level1.tscn
+```
+
+**Godot 路径优先级：**
+1. `--godot` 命令行参数（最高优先级）
+2. `GODOT_PATH` 环境变量
+3. 如果都未指定，将显示错误提示
+
+**参数说明：**
+
+| 参数 | 说明 |
+|------|------|
+| `--godot PATH` | 指定 Godot 可执行文件路径（优先级高于环境变量） |
+| `--scene PATH` | 指定要导出的场景文件路径，`res://` 前缀可选（默认：`res://main.tscn`） |
+
+
+### 编辑器菜单导出
+
+> **前提条件**：需要先在 Godot 编辑器中启用插件（**项目 > 项目设置 > 插件**）
+
+启用插件后，可通过 **项目 > 工具** 菜单访问导出功能：
+
+| 菜单项 | 功能 |
+|--------|------|
+| **SPX Export TileMap...** | 仅导出当前场景的 TileMap 数据 |
+| **SPX Export Decorators...** | 仅导出当前场景的装饰器数据 |
+| **SPX Export All...** | 同时导出 TileMap 和装饰器数据 |
+
+
+### 直接使用 Godot CLI
+
+如果需要更精细的控制，也可以直接使用 Godot 命令行：
+
+```bash
+# 基础用法（导出默认场景 res://main.tscn）
+godot --headless --path <项目路径> -s addons/spx_tilemap_exporter/export_cli.gd
+
+# 导出指定场景
+godot --headless --path <项目路径> -s addons/spx_tilemap_exporter/export_cli.gd -- --scene res://levels/level1.tscn
+```
+
+| 参数 | 说明 |
+|------|------|
+| `--scene <path>` | 指定要导出的场景路径（必须放在 `--` 之后） |
+
+## 导出输出
+
+导出文件保存在 `res://_export/<场景名>/` 目录：
+
+```
+_export/
+└── <场景名>/
+    ├── tilemap.json        # TileMap 数据
+    ├── tilemap/            # TileMap 纹理目录
+    │   └── *.png
+    ├── decorator.json      # 装饰器数据
+    └── decorator/          # 装饰器纹理目录
+        └── *.png
+```
+
+## 配置
+
+### CLI 脚本配置
+
+编辑 `export_cli.gd` 中的常量来修改默认配置：
+
+```gdscript
+const DEFAULT_SCENE_PATH = "res://main.tscn"  # 默认导出的场景路径
+const EXPORT_TILEMAP = true                   # 是否导出 TileMap
+const EXPORT_DECORATORS = true                # 是否导出装饰器
+```
+
+### 排除节点
+
+装饰器导出时会自动排除以下节点：
+
+- 属于 `spx_ignore` 组的节点
+- TileMapLayer 和 TileMap 节点（单独导出）
+- 名称包含 `_ignore` 或 `_skip` 的节点
+
+## 文件说明
+
+| 文件 | 描述 |
+|------|------|
+| `plugin.cfg` | 插件配置文件 |
+| `spx_tilemap_exporter.gd` | 主插件脚本，提供编辑器菜单功能 |
+| `tilemap_extractor.gd` | TileMap 数据提取和导出逻辑 |
+| `decorator_extractor.gd` | 装饰器数据提取和导出逻辑 |
+| `export_cli.gd` | 命令行导出脚本（Godot --headless 模式） |
+| `export.py` | Python 自动化导出脚本 |
+
+
+## 环境要求
+
+- Godot 4.x
+- Python 3.8+（使用 Python 导出脚本时）
+
+---
+
+## 引擎开发者
+
+> 以下内容仅供 SPX 引擎开发者参考，普通用户可忽略此章节。
+
+### 插件快速迭代
+
+在开发 `spx_tilemap_exporter` 插件时，可以使用 `--copy` 参数将最新的插件代码从引擎源码目录复制到目标项目：
+
+```bash
+# 带 addon 复制的导出（从源码复制最新插件到项目目录）
+python export.py --copy
+
+# 组合使用：复制插件并导出指定场景
+python export.py --copy --scene my_scene.tscn
+
+# 组合使用：指定 Godot 路径、复制插件并导出指定场景
+python export.py --godot /path/to/godot --copy --scene my_scene.tscn
+```
+
+| 参数 | 说明 |
+|------|------|
+| `--godot PATH` | 指定 Godot 可执行文件路径（优先级高于 `GODOT_PATH` 环境变量） |
+| `--copy` | 从 `pkg/gdspx/godot/addons/` 复制最新的插件到当前项目目录，用于快速迭代插件开发 |
+
+**工作流程：**
+
+1. 在 `pkg/gdspx/godot/addons/spx_tilemap_exporter/` 修改插件代码
+2. 进入测试项目目录（如 `tutorial/AA-00Town/`）
+3. 运行 `python export.py --copy` 自动复制插件并测试导出
+
+## 许可证
+
+SPX Team © 2026