Skip to content

Commit 21b933d

Browse files
Seeker0472Seeker0472
committed
docs: document starrysky mc server release
1 parent 4af9b71 commit 21b933d

8 files changed

Lines changed: 784 additions & 222 deletions

File tree

‎AGENTS.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# AGENTS
2+
3+
## Project Overview
4+
5+
`mc-uart-server` is a minimal Minecraft Java Edition 1.8.x server for the StarrySky C2 board. A local Minecraft client connects to a Rust TCP-to-UART bridge on the host, and the bridge forwards Minecraft TCP bytes over a custom UART link to C firmware running on the board.
6+
7+
Current release target:
8+
9+
- Board: StarrySky C2.
10+
- Minecraft protocol: Java 1.8.x / protocol 47.
11+
- Authentication: offline mode, no encryption or online session validation.
12+
- Players: single player.
13+
- Default firmware: Minecraft protocol compression enabled, spawn chunks precompressed at build time and copied to PSRAM at boot.
14+
- Default UART roles: UART0/SYS_UART/type-c for bridge data, UART1/HP_UART for firmware logs.
15+
16+
## Documentation Index
17+
18+
- [README.md](README.md): human-facing Chinese overview, quick build, and run flow.
19+
- [docs/README.md](docs/README.md): Chinese documentation reading path.
20+
- [docs/architecture.md](docs/architecture.md): architecture across the host bridge, custom UART link, firmware server, map data, and logging.
21+
- [docs/build-and-run.md](docs/build-and-run.md): reproducible build and run instructions.
22+
- [docs/compressed-map-psram.md](docs/compressed-map-psram.md): default compressed-map PSRAM firmware behavior.
23+
- [docs/protocol/uart-link-v2.md](docs/protocol/uart-link-v2.md): custom UART link v2 frame format, handshake, flow control, reset, and error behavior.
24+
- [docs/protocol/references.md](docs/protocol/references.md): upstream references for Minecraft 1.8, StarrySky C2, ECOS SDK, and protocol choices.
25+
26+
## Code Map
27+
28+
- `core/`: platform-independent C code for Minecraft protocol handling, the server state machine, UART link codec, ring buffers, and world data.
29+
- `firmware/`: StarrySky C2 firmware entry point, UART/PSRAM/SDK adapters, link session scheduling, and logging.
30+
- `bridge/`: Rust TCP-to-UART bridge with serial framing, rate calibration, retransmission, and serverbound movement filtering.
31+
- `native/`: host-side C tests.
32+
- `nix/`: Nix package definitions for firmware, bridge, native tests, and Windows bridge cross-builds.
33+
- `scripts/generate_compressed_chunks.py`: generator for the default 3x3 compressed spawn chunk assets.
34+
35+
## Tooling
36+
37+
- If a task needs a command-line tool that is not installed locally, prefer using
38+
Nix to obtain it temporarily, for example with `nix shell nixpkgs#<package>`
39+
or `nix run nixpkgs#<package>`.
40+
- Do not commit Nix result symlinks such as `result`, `result-*`, or similar
41+
build output links.
42+
- If obtaining or running the tool requires network access, broader filesystem
43+
access, or elevated sandbox permissions, ask the user for approval first.

‎README.md‎

Lines changed: 97 additions & 111 deletions
Original file line numberDiff line numberDiff line change
@@ -1,167 +1,153 @@
1-
# MC UART Server
1+
# StarrySky MC-Server
22

3-
Minimal Minecraft Java Edition 1.8.x server for StarrySky C2 using a UART byte stream.
3+
`starrysky-mc-server` 是一个给 StarrySky C2 板卡运行的最小 Minecraft Java Edition 1.8.x 服务器。它不是通用 Minecraft 服务端；目标是把协议、地图和传输栈压到 C2 的资源约束里，让本机 Minecraft 客户端通过串口和板卡上的固件交互。
44

5-
## Target
5+
默认发布配置面向 Minecraft Java 1.8.x / protocol 47，离线模式，单人，启用协议压缩。主机侧 Rust bridge 监听 `127.0.0.1:25565`，把 TCP 字节流转换成项目自定义的 UART link v2 帧；板卡固件在 UART0/SYS_UART/type-c 上接收桥接数据，在 UART1/HP_UART 上输出日志。
66

7-
- Board: StarrySky C2
8-
- CPU: PicoRV32 RV32IMAC, 72 MHz
9-
- Default bridge data link: UART0/SYS_UART/type-c at 115200 baud
10-
- Default log output: UART1/HP_UART at 115200 baud
11-
- Minecraft protocol: Java Edition 1.8.x, protocol version 47
12-
- Server mode: offline, no encryption, protocol compression enabled, one player
13-
14-
## Architecture
7+
## 运行架构
158

169
```text
17-
Minecraft client
10+
Minecraft Java 1.8.x client
1811
<-> TCP 127.0.0.1:25565
19-
<-> Rust bridge
20-
<-> type-c serial port at 115200 baud
12+
<-> bridge/mc-uart-bridge
13+
<-> UART link v2 over 115200 baud serial
2114
<-> StarrySky C2 UART0/SYS_UART
22-
<-> C server core
15+
<-> firmware/main.c
16+
<-> core Minecraft server
2317
2418
Firmware logs
2519
-> StarrySky C2 UART1/HP_UART at 115200 baud
2620
```
2721

28-
## Commands
22+
核心分层：
23+
24+
- `core/` 是平台无关 C 代码，包含 Minecraft VarInt/packet writer、服务器状态机、link codec、环形缓冲、默认世界和压缩 chunk 运行时。
25+
- `firmware/` 绑定 StarrySky C2 SDK，负责 UART、PSRAM、主循环、link session、日志和复位后的会话清理。
26+
- `bridge/` 是 Rust 主机工具，负责 TCP 监听、串口帧解码、PC-to-firmware ACK/重传、速率探测和 movement 包过滤。
27+
- `nix/` 是可复现构建入口，默认固件构建会生成压缩地图资产，并导出固件内存占用报告。
28+
29+
更完整的实现说明见 [docs/README.md](docs/README.md) 和 [docs/architecture.md](docs/architecture.md)。
30+
31+
## 目标平台与默认配置
32+
33+
- Board：StarrySky C2。
34+
- CPU：PicoRV32 RV32IMAC，72 MHz。
35+
- 内存：片上 SRAM 128 KiB，外部 PSRAM 8 MiB。
36+
- 默认 bridge UART：UART0/SYS_UART/type-c，115200 baud。
37+
- 默认 log UART：UART1/HP_UART，115200 baud。
38+
- Minecraft：Java Edition 1.8.x，protocol 47。
39+
- 服务端模式：offline，无加密，单人。
40+
- 默认地图：3x3 spawn chunks，superflat 风格，离线 zlib 压缩后在启动时复制到 PSRAM。
41+
42+
## 快速构建
43+
44+
推荐使用 Nix：
2945

3046
```bash
31-
nix build
3247
nix build .#native-tests
3348
nix build .#bridge
34-
nix flake check
35-
nix develop
49+
nix build .#firmware-c2
3650
```
3751

38-
Inside `nix develop`:
52+
常用包：
3953

4054
```bash
41-
make firmware
42-
make test-native
43-
make bridge
55+
nix build .#firmware-c2
56+
nix build .#firmware-c2-aggressive
57+
nix build .#firmware-c2-legacy
58+
nix build .#log-debug
59+
nix build .#bridge-windows
60+
nix flake check
4461
```
4562

46-
Firmware builds print an upstream-style memory usage table in the Nix build
47-
log and install the same table beside the firmware artifacts:
63+
也可以进入开发 shell 后使用 Make 包装命令：
4864

4965
```bash
50-
nix build .#firmware-c2
51-
cat result/memory-report.txt
66+
nix develop
67+
make test-native
68+
make bridge
69+
make firmware
5270
```
5371

54-
The report separates FLASH, SRAM, and PSRAM. The PSRAM row includes explicit
55-
runtime arena usage such as the compressed-map assets copied into PSRAM at
56-
boot.
72+
固件产物在 `result/` 下：
5773

58-
## UART Roles and Logging
59-
60-
Firmware UART configuration lives in `firmware/mc_firmware_config.h`.
61-
62-
Defaults:
63-
64-
```c
65-
#define MC_UART0_BAUD 115200u
66-
#define MC_UART1_BAUD 115200u
67-
#define MC_BRIDGE_UART_ID MC_UART_ID_0
68-
#define MC_LOG_UART_ID MC_UART_ID_1
69-
#define MC_LOG_LEVEL MC_LOG_INFO
70-
```
74+
- `mc_uart_fw.bin`：用于刷写的固件镜像。
75+
- `mc_uart_fw.elf` / `mc_uart_fw`：ELF。
76+
- `mc_uart_fw.hex`：HEX。
77+
- `mc_uart_fw.txt`：反汇编文本。
78+
- `memory-report.txt`：FLASH、SRAM、PSRAM 占用报告。
7179

72-
`MC_BRIDGE_UART_ID` and `MC_LOG_UART_ID` must be different so firmware logs never share the bridge data link. To reverse the UART responsibilities, set `MC_BRIDGE_UART_ID` to `MC_UART_ID_1` and `MC_LOG_UART_ID` to `MC_UART_ID_0` in a local development override.
80+
构建与运行细节见 [docs/build-and-run.md](docs/build-and-run.md)。
7381

74-
Firmware logging supports `MC_LOG_OFF`, `MC_LOG_INFO`, `MC_LOG_DEBUG`, and `MC_LOG_TRACE`. `INFO` logs boot, link, state, and error events; `DEBUG` adds more detailed packet and byte-flow diagnostics; `TRACE` adds raw received data dumps.
82+
## 运行 Bridge
7583

76-
The maintained debug firmware keeps the default compressed-map PSRAM profile and selects `MC_LOG_DEBUG`:
84+
Linux 示例：
7785

7886
```bash
79-
nix build .#log-debug
87+
mc-uart-bridge --serial /dev/ttyUSB0 --baud 115200 --listen 127.0.0.1:25565
8088
```
8189

82-
## Reference Policy
83-
84-
Do not guess board registers, UART status bits, memory ranges, Minecraft packet IDs, packet fields, or chunk layouts. Check `docs/protocol/references.md` before changing those areas.
90+
Windows 示例：
8591

86-
## Flashing
92+
```powershell
93+
.\mc-uart-bridge.exe --serial COM5 --baud 115200 --listen 127.0.0.1:25565
94+
```
8795

88-
Automatic flashing is not part of this project. The build produces firmware artifacts only.
96+
需要导出 bridge 日志时，PowerShell 推荐把日志写到当前目录：
8997

90-
## Running the Bridge
98+
```powershell
99+
$log = ".\bridge-$(Get-Date -Format yyyyMMdd-HHmmss).log"
100+
cmd /c ".\mc-uart-bridge.exe --serial COM5 --baud 115200 --listen 127.0.0.1:25565 --verbose 2>&1" | Tee-Object -FilePath $log
101+
```
91102

92-
The bridge and firmware use UART link protocol V2. V2 frames are COBS-encoded
93-
and terminated with `0x00`, so corrupted frames are discarded at the next
94-
delimiter. PC-to-firmware DATA frames use stop-and-wait ACK/retransmission and
95-
absolute ACK credit. Firmware-to-PC DATA frames are not ACKed in this version;
96-
the bridge treats any decode, CRC, or DATA_M2C sequence error as fatal and exits
97-
so link corruption is visible during testing.
103+
启动 Minecraft Java Edition 1.8.x，添加服务器 `127.0.0.1:25565`。
98104

99-
The default `firmware-c2` package uses Minecraft protocol compression, offline
100-
precompressed spawn chunks, and PSRAM runtime chunk storage. Build
101-
`firmware-c2-legacy` only when you need the old SRAM map fallback.
105+
## 协议和传输
102106

103-
After the bootstrap chunks are queued, the firmware sends Play KeepAlive
104-
packets on a fixed interval. KeepAlive ids advance each interval; replies clear
105-
the pending marker for diagnostics, but the firmware does not disconnect the
106-
Minecraft session for missed replies. Reset the board when you need to force a
107-
fresh server session.
107+
Minecraft 层：
108108

109-
MCU-to-PC firmware transmit is conservative by default. Build
110-
`firmware-c2-aggressive` to use the validated MCU-to-PC aggressive profile; it
111-
keeps the stable frame size, TX budget, UART burst, and 115200 baud, and lowers
112-
only UART0 TX pacing.
109+
- 握手和 Status 请求使用普通 Minecraft frame。
110+
- Login 阶段默认先发送 `Set Compression`，再发送压缩格式的 `Login Success`。
111+
- Play 阶段发送 Join Game、Spawn Position、Time、Health、Player Position And Look、spawn chunks 和 KeepAlive。
112+
- KeepAlive id 每次递增；客户端 ACK 只用于诊断，固件不会因为 missed keepalive 主动踢出玩家。
113113

114-
PC-to-firmware traffic remains conservative. It calibrates per-byte pacing with
115-
RATE_PROBE frames, waits for the link to settle, warms up at the slowest profile,
116-
then requires three formal probes per profile. A 3/3 profile is stable; a 2/3
117-
profile is treated as borderline and stops probing. Real DATA is written one
118-
byte at a time using one supported profile slower than the fastest stable or
119-
borderline result, and downshifts on retransmit timeouts.
114+
UART link v2：
120115

121-
The bridge drops Minecraft 1.8 serverbound movement packets before forwarding
122-
PC-to-firmware DATA so idle movement spam cannot fill the UART link. KeepAlive
123-
responses and other serverbound packets are preserved.
116+
- 帧体包含 version、type、flags、seq、ack、payload length、payload 和 CRC16。
117+
- 整帧用 COBS 编码，并以 `0x00` 分隔。
118+
- PC-to-firmware DATA 使用 stop-and-wait、ACK、绝对 credit 和超时重传。
119+
- Firmware-to-PC DATA 当前不做 ACK；bridge 遇到解码、CRC 或 `DATA_M2C sequence mismatch` 会退出，让链路损坏在测试时显性暴露。
120+
- Bridge 会丢弃 Minecraft 1.8 serverbound movement 包，避免客户端空闲移动上报填满低速 UART；KeepAlive 回复和非 movement 包会继续转发。
124121

125-
The default bridge UART baud remains 115200 for conservative bring-up and for
126-
the validated aggressive profile. If you build custom firmware with a different
127-
`MC_UART0_BAUD` or `MC_UART1_BAUD`, run the bridge with the matching `--baud`
128-
value.
122+
自定义 UART link v2 的完整格式见 [docs/protocol/uart-link-v2.md](docs/protocol/uart-link-v2.md)。协议来源和具体选择见 [docs/protocol/references.md](docs/protocol/references.md)。
129123

130-
```bash
131-
nix build .#firmware-c2
132-
nix build .#firmware-c2-legacy
133-
nix build .#firmware-c2-aggressive
134-
nix build .#log-debug
135-
```
124+
## UART 与日志
136125

137-
Use `log-debug` firmware for gameplay tests that need firmware diagnostics.
138-
`MC_LOG_TRACE` is intended only for short local diagnostics because raw frame
139-
dumps can slow the firmware main loop enough to change UART timing.
126+
固件 UART 配置在 [firmware/mc_firmware_config.h](firmware/mc_firmware_config.h)：
140127

141-
Linux example:
142-
143-
```bash
144-
mc-uart-bridge --serial /dev/ttyUSB0 --baud 115200 --listen 127.0.0.1:25565
128+
```c
129+
#define MC_UART0_BAUD 115200u
130+
#define MC_UART1_BAUD 115200u
131+
#define MC_BRIDGE_UART_ID MC_UART_ID_0
132+
#define MC_LOG_UART_ID MC_UART_ID_1
133+
#define MC_LOG_LEVEL MC_LOG_INFO
145134
```
146135
147-
Windows example:
148-
149-
```powershell
150-
mc-uart-bridge.exe --serial COM3 --baud 115200 --listen 127.0.0.1:25565
151-
```
136+
`MC_BRIDGE_UART_ID` 和 `MC_LOG_UART_ID` 必须不同，避免日志字节污染 bridge 数据链路。
152137
153-
During MCU-to-PC testing, a bridge exit with a serial decode error, CRC error,
154-
or `DATA_M2C sequence mismatch` means the link lost or corrupted bytes.
138+
日志级别：
155139
156-
The bridge waits `1000ms` before retransmitting unacknowledged PC-to-firmware
157-
DATA by default. Use `--c2m-retransmit-timeout-ms` only when intentionally
158-
testing PC-to-firmware behavior; the stable and aggressive firmware profiles do
159-
not require changing it.
140+
- `MC_LOG_OFF`：关闭日志。
141+
- `MC_LOG_INFO`：启动、登录、连接复位和关键错误。
142+
- `MC_LOG_DEBUG`：额外的帧、KeepAlive、回压和链路诊断。
143+
- `MC_LOG_TRACE`：原始数据 dump，仅用于短时诊断，可能改变串口时序。
160144
161-
Build a Windows bridge executable from Nix on Linux:
145+
`log-debug` 包使用默认压缩地图 PSRAM 配置，并把固件日志级别设为 `MC_LOG_DEBUG`：
162146
163147
```bash
164-
nix build .#bridge-windows
148+
nix build .#log-debug
165149
```
166150

167-
Start Minecraft Java Edition 1.8.x and add server `127.0.0.1:25565`.
151+
## 参考来源
152+
153+
Minecraft 1.8、StarrySky C2、ECOS SDK 和本项目协议选择的来源见 [docs/protocol/references.md](docs/protocol/references.md)。

‎docs/README.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# 文档索引
2+
3+
本目录是发布给读者看的中文文档。实现细节以当前源码和构建脚本为准；如果文档与源码冲突，先修正文档或测试，再发布。
4+
5+
## 阅读路径
6+
7+
1. [架构说明](architecture.md)：先理解 Minecraft 客户端、Rust bridge、UART link v2、C2 固件和 core server 的数据流。
8+
2. [编译与复现](build-and-run.md)：按 Nix 构建 native tests、bridge 和固件，并运行本机 Minecraft 连接测试。
9+
3. [压缩地图与 PSRAM 固件](compressed-map-psram.md)：理解默认 `firmware-c2` 如何生成、复制和发送压缩 spawn chunks。
10+
4. [UART link v2](protocol/uart-link-v2.md)：理解本项目自定义 UART 帧协议、握手、流控、重传和错误处理。
11+
5. [协议与参考来源](protocol/references.md)：核对 Minecraft 1.8、StarrySky C2、SDK、本项目协议常量和源码锚点。
12+
13+
## 维护原则
14+
15+
- 写架构事实时引用当前源码路径，不用旧日志或记忆替代。
16+
- 写构建命令时必须能在当前仓库根目录运行。
17+
- 写资源占用时优先指向 `result/memory-report.txt`，不要固化某次构建的临时数字。
18+
- 修改 Minecraft packet id、UART link 常量、固件 profile 或 Nix 输出时，同步更新对应文档。

0 commit comments

Comments
 (0)