feat(spx_tilemap_exporter): add Python export script and documentation by JiepengTan · Pull Request #243 · goplus/godot

JiepengTan · 2026-01-23T07:46:25Z

Add export.py for automated TileMap data export workflow
Add README.md and README.zh.md with complete usage documentation
Improve export_cli.gd with better CLI support
Support Godot path via --godot arg or GODOT_PATH env var

Quick Start

# 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

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

test project: AA-01Platform.zip

- Add export.py for automated TileMap data export workflow - Add README.md and README.zh.md with complete usage documentation - Improve export_cli.gd with better CLI support - Support Godot path via --godot arg or GODOT_PATH env var

gemini-code-assist · 2026-01-23T07:46:44Z

Summary of Changes

Hello @JiepengTan, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the SPX TileMap Exporter by introducing a new Python-based automation script, making the export workflow more streamlined and user-friendly. It also improves the existing Godot CLI script to allow for dynamic scene selection and provides comprehensive, localized documentation to ensure developers can easily set up and utilize the tool. These changes aim to simplify the process of exporting game assets from Godot to the SPX runtime.

Highlights

Automated Export Workflow: Introduced a new Python script (export.py) to automate the entire TileMap and decorator data export process, including optional addon copying and project resource importing.
Comprehensive Documentation: Added detailed README files in both English (README.md) and Chinese (README.zh.md) to guide users through installation, usage, features, and configuration of the exporter.
Enhanced CLI Support: Improved the Godot CLI export script (export_cli.gd) to accept a '--scene' argument, allowing users to specify which scene to export directly from the command line.
Flexible Godot Path Detection: The Python export script now supports specifying the Godot executable path via a command-line argument (--godot) or an environment variable (GODOT_PATH), with clear priority.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	`/gemini review`	Performs a code review for the current pull request in its current state.
Pull Request Summary	`/gemini summary`	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	`/gemini help`	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

xgopilot · 2026-01-23T07:49:31Z

addons/spx_tilemap_exporter/export.py

+    set_godot_path_override(args.godot)
+
+    # Get the directory where this script is located (works regardless of where it's executed from)
+    script_dir = Path(__file__).resolve().parent.parent.parent


Path calculation mismatch: Lines 257-260 calculate script_dir by going up 3 parent levels from export.py, but the README instructs users to place this script at addons/spx_tilemap_exporter/export.py. This inconsistency means:

Going up 3 levels from addons/spx_tilemap_exporter/export.py reaches an incorrect location

The --copy feature will fail for users following the Quick Start guide

The comment on line 259 says "script is under tutorial/AA-00Town" which contradicts the README documentation (line 15).

Suggestion: Either fix the path calculation to match the documented structure, or clarify in the README that this script is specifically for engine developers working in the tutorial/AA-00Town/ directory.

xgopilot · 2026-01-23T07:49:34Z

addons/spx_tilemap_exporter/export.py

+
+
+# Global variable to store Godot path from command line argument
+_godot_path_override: Path | None = None


Code simplification: The global variable pattern with _godot_path_override and set_godot_path_override() adds unnecessary complexity. Consider passing the override path directly as a parameter to get_godot_path() to eliminate global state and improve testability.

xgopilot · 2026-01-23T07:49:35Z

addons/spx_tilemap_exporter/export.py

+
+    # Priority 1: Command line argument
+    if _godot_path_override:
+        if not _godot_path_override.exists():


Duplicate validation logic: The path existence check is duplicated for both _godot_path_override and GODOT_PATH environment variable. Consider extracting this into a helper function to reduce duplication.

xgopilot · 2026-01-23T07:49:37Z

addons/spx_tilemap_exporter/export.py

+
+    # Execute command
+    try:
+        result = subprocess.run(cmd, cwd=str(script_dir))


Missing timeout: Consider adding a timeout parameter to prevent the process from hanging indefinitely on large projects or if Godot encounters an issue:

result = subprocess.run(cmd, cwd=str(script_dir), timeout=600)

xgopilot · 2026-01-23T07:49:40Z

addons/spx_tilemap_exporter/export.py

+    print("")
+
+    # Execute command
+    try:


Duplicate subprocess pattern: Both import_project() and run_export() have nearly identical subprocess error handling (try/except with return code checking). Consider extracting a helper function like run_godot_command() to eliminate this duplication.

xgopilot · 2026-01-23T07:49:40Z

Code Review Summary

This PR adds comprehensive Python export tooling and documentation for the SPX TileMap Exporter. The code is well-structured with good documentation coverage.

Key findings:

Critical: Path calculation in export.py conflicts with README instructions - the --copy feature won't work as documented
Documentation gap: Missing JSON output format specification for SPX runtime integration
Code quality: Some opportunities for simplification (global state, duplicate validation logic)
Security: Good use of list-based subprocess calls prevents command injection

The implementation is solid for a development tool, with no critical security issues found.

gemini-code-assist

Code Review

This pull request introduces a Python script to automate the TileMap data export workflow, along with comprehensive documentation in both English and Chinese. The changes also improve the existing Godot CLI export script by adding support for specifying a scene via command-line arguments.

My review focuses on improving the clarity of the new documentation and code. I've pointed out some inconsistencies in the README examples that could confuse users. I've also suggested improvements to variable naming in the new Python script for better maintainability, and a fix in the GDScript to align its behavior with the documented intention for creating export paths. Overall, this is a great addition that will significantly improve the developer experience.

gemini-code-assist · 2026-01-23T07:50:16Z

addons/spx_tilemap_exporter/README.md

+**Method 1: Specify Godot path via command line argument**
+
+```bash
+python export.py --godot /path/to/godot --scene levels/level1.tscn


The example command for running the export script is missing the full path to the script. Assuming the user is at the project root, the command should be python addons/spx_tilemap_exporter/export.py .... This is inconsistent with the "Quick Start" section and might confuse users. This applies to other examples in this file as well.

Suggested change

python export.py --godot /path/to/godot --scene levels/level1.tscn

python addons/spx_tilemap_exporter/export.py --godot /path/to/godot --scene levels/level1.tscn

gemini-code-assist · 2026-01-23T07:50:16Z

addons/spx_tilemap_exporter/README.zh.md

+**方式一：通过命令行参数指定 Godot 路径**
+
+```bash
+python export.py --godot /path/to/godot --scene levels/level1.tscn


运行导出脚本的示例命令缺少脚本的完整路径。假设用户位于项目根目录，命令应该是 python addons/spx_tilemap_exporter/export.py ...。这与“快速开始”部分不一致，可能会让用户感到困惑。此问题也存在于文件中的其他示例。

Suggested change

python export.py --godot /path/to/godot --scene levels/level1.tscn

python addons/spx_tilemap_exporter/export.py --godot /path/to/godot --scene levels/level1.tscn

gemini-code-assist · 2026-01-23T07:50:17Z

addons/spx_tilemap_exporter/export.py

+    script_dir = Path(__file__).resolve().parent.parent.parent
+
+    # Calculate project root directory (script is under tutorial/AA-00Town, go up two levels)
+    project_root = script_dir.parent.parent


The variable script_dir is misleadingly named. Based on its calculation (Path(__file__).resolve().parent.parent.parent), it points to the Godot project's root directory, not the script's directory. The comment on line 257 is also incorrect. Similarly, project_root is confusing as it points to the root of the monorepo, not the Godot project.

For better clarity and maintainability, I suggest renaming these variables to reflect their actual purpose throughout the file, for example:

script_dir -> project_dir

project_root -> monorepo_root

This would make the code easier to understand, especially the logic in copy_addon and the cwd parameter in subprocess.run.

gemini-code-assist · 2026-01-23T07:50:17Z

addons/spx_tilemap_exporter/export_cli.gd

+	var export_path = scene_path.get_file().get_basename()
+	var export_base = "res://_export/" + export_path


There's a discrepancy between the comment and the implementation for generating the export path. The comment suggests that a scene path like "res://levels/level1.tscn" should result in an export path of "res://_export/levels/level1", which is great for avoiding filename conflicts.

However, the current implementation var export_path = scene_path.get_file().get_basename() will result in "res://_export/level1", losing the subdirectory structure.

To match the behavior described in the comment, you could modify the implementation.

var export_path = scene_path.replace("res://", "").trim_suffix("." + scene_path.get_extension()) var export_base = "res://_export/" + export_path

JiepengTan requested a review from joeykchen January 23, 2026 07:46

xgopilot bot reviewed Jan 23, 2026

View reviewed changes

gemini-code-assist bot reviewed Jan 23, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(spx_tilemap_exporter): add Python export script and documentation#243

feat(spx_tilemap_exporter): add Python export script and documentation#243
JiepengTan wants to merge 1 commit intogoplus:spx4.4.1from
JiepengTan:pr_addon_export_tilemap_preview_png

JiepengTan commented Jan 23, 2026 •

edited

Loading

Uh oh!

gemini-code-assist bot commented Jan 23, 2026

Uh oh!

xgopilot bot Jan 23, 2026

Uh oh!

xgopilot bot Jan 23, 2026

Uh oh!

xgopilot bot Jan 23, 2026

Uh oh!

xgopilot bot Jan 23, 2026

Uh oh!

xgopilot bot Jan 23, 2026

Uh oh!

xgopilot bot commented Jan 23, 2026

Uh oh!

gemini-code-assist bot left a comment

Uh oh!

gemini-code-assist bot Jan 23, 2026

Uh oh!

gemini-code-assist bot Jan 23, 2026

Uh oh!

gemini-code-assist bot Jan 23, 2026

Uh oh!

gemini-code-assist bot Jan 23, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant



		# Global variable to store Godot path from command line argument
		_godot_path_override: Path \| None = None

	python export.py --godot /path/to/godot --scene levels/level1.tscn
	python addons/spx_tilemap_exporter/export.py --godot /path/to/godot --scene levels/level1.tscn

		var export_path = scene_path.get_file().get_basename()
		var export_base = "res://_export/" + export_path

Conversation

JiepengTan commented Jan 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Quick Start

Uh oh!

gemini-code-assist bot commented Jan 23, 2026

Summary of Changes

Highlights

Footnotes

Uh oh!

xgopilot bot Jan 23, 2026

Choose a reason for hiding this comment

Uh oh!

xgopilot bot Jan 23, 2026

Choose a reason for hiding this comment

Uh oh!

xgopilot bot Jan 23, 2026

Choose a reason for hiding this comment

Uh oh!

xgopilot bot Jan 23, 2026

Choose a reason for hiding this comment

Uh oh!

xgopilot bot Jan 23, 2026

Choose a reason for hiding this comment

Uh oh!

xgopilot bot commented Jan 23, 2026

Code Review Summary

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist bot Jan 23, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Jan 23, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Jan 23, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Jan 23, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

JiepengTan commented Jan 23, 2026 •

edited

Loading