# cxpython

**Repository Path**: rtccn_mc/cxpython

## Basic Information

- **Project Name**: cxpython
- **Description**: cxpython(全称command xpython mod)
提供类似于python的全新游戏内(注意是游戏内的)逻辑脚本编写
为游戏原本的 微型处理器、逻辑处理器和超核处理器 拓展更多能力
power by Mindustry mod api -JAR Mod
- **Primary Language**: Unknown
- **License**: GPL-3.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-29
- **Last Updated**: 2026-08-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# cxpython — command xPython mod

一个为 **Mindustry** 开发的模组：新增一个自定义"逻辑控制器"方块，玩家可以用**类似 Python 的脚本**（`.xpy`）编写游戏内控制逻辑。内置一个轻量仿 Python 解释器，无需担心卡顿——脚本按游戏 **tick 限量执行**，可持续常驻运行。

> 底层类似游戏原生逻辑处理器，但用熟悉、易读的 Python 风格语言。

---

## ✨ 功能特性

- **仿 Python 语言**：变量、`if/elif/else`、`while/for`、`def/return`、`break/continue`、列表/字典、函数
- **持续逐 tick 执行**：每 tick 限量运行约 4000 条指令，预算耗尽自动续跑，`while True` 不会卡死游戏
- **跨方块 `import`**：每个方块可起唯一名字，其他方块可直接把它当脚本库导入；自带循环导入检测
- **世界 I/O**：`link / links / sensor / read / write`，读取与操控周围建筑与内存单元
- **控兵**：`bind` 绑定本方单位，用索引操控移动、停止、击杀、旗标等
- **文件系统**：脚本内 `writeFile / readFile / fileExists` 持久化数据；编辑器可**导出/导入**脚本
- **UI 编辑器**：点击方块右键即可编辑脚本、命名、运行/停止，实时日志窗口
- **生命周期钩子**：`onEnable / onDisable` 在启动/停止时自动触发
- **外部扩展 API**：其他模组可用 `PyLogicApi` 注入自定义内建函数、控制逻辑方块
- **双端兼容**：桌面版 + Android 版单一 JAR

---

## 🚀 快速开始

1. 下载 `releases/cxpython.jar`，放入游戏模组目录，进游戏启用模组。
2. 在**逻辑**分类里放置 **PyLogic 处理器**方块。
3. 右键方块 → 打开编辑器 → 粘贴脚本、起名 → 点「运行」→ 开启日志查看输出。

一个最简脚本：

```python
# 每 tick 输出一次单位数量到日志
print("hello cxpython")
```

一个控兵示例：

```python
n = bind("dagger")
for i in range(n):
    if unitHealth(i) < unitMaxHealth(i) * 0.5:
        unitStop(i)          # 残血休整
    else:
        unitMove(i, 10, 10, 2.0)   # 满血向 (10,10) 集结
```

更多完整示例见 [examples/unit-patrol.xpy](examples/unit-patrol.xpy)。

---

## 📚 文档索引

| 文档 | 内容 |
|---|---|
| [docs/xpy-language.md](docs/xpy-language.md) | `.xpy` 脚本语言语法（类型、运算符、控制流、函数、import、钩子） |
| [docs/builtin-functions.md](docs/builtin-functions.md) | 全部内建函数名表（核心/世界 I/O/UI/文件/控兵） |
| [docs/mod-api.md](docs/mod-api.md) | 面向其他模组的 `PyLogicApi` 对外互操作 API |
| [docs/technical-details.md](docs/technical-details.md) | 协作者上手：架构分层、限量续跑原理、扩展指南 |
| [docs/build-packaging.md](docs/build-packaging.md) | 完整打包流程（桌面 + Android） |

**示例脚本**
- [examples/unit-patrol.xpy](examples/unit-patrol.xpy) — 编队巡逻（绑定 dagger，A/B 两点往返 + 残血休整）

---

## 🛠 环境要求

- **开发/编译**：JDK 17、Gradle 8（详见 `docs/build-packaging.md`）
- **运行**：Mindustry `v159.7`（桌面 / Android 均可）

---

## 📦 构建发布

构建与打包（桌面 + Android 合并 JAR）见 [docs/build-packaging.md](docs/build-packaging.md)。

一次完整构建概要：

```bash
# 1. 编译桌面 JAR
gradle -Dorg.gradle.java.home=$JAVA17 --no-daemon jar

# 2. 生成 Android 字节码、3. 合并单一发行版 JAR（详见文档）
```

---

## 📄 开源

本项目采用 **GPL-3.0** 协议，详见 [LICENSE](LICENSE)。欢迎自由参考、修改与贡献。