this repo has no description
1# Star Rod Command-Line Interface
2
3Star Rod provides a comprehensive CLI for automation, scripting, and headless builds.
4
5## General Commands
6
7### Help
8```bash
9java -jar StarRod.jar help
10```
11Display all available commands with usage examples.
12
13### Version
14```bash
15java -jar StarRod.jar version
16```
17Show version information.
18
19---
20
21## Project Building
22
23### Build Diorama Package
24```bash
25java -jar StarRod.jar build
26```
27Build a complete Diorama distribution package.
28
29**Output:** `.starrod/build/<mod-id>.diorama`
30
31**What it does:**
321. Compiles all project assets (maps, sprites, textures, etc.)
332. Compresses binary data using Yay0 compression
343. Packages into AssetsArchive format
354. Includes project.kdl manifest
365. Generates target.json with engine SHA and configuration
376. Packages everything into a TAR.GZ archive
38
39**Use cases:**
40- Standard build command for development
41- Creating release packages for distribution
42- Automated build pipelines
43- Continuous integration
44
45### Build AssetsArchive Only
46```bash
47java -jar StarRod.jar archive
48```
49Build only the AssetsArchive (assets.bin) without packaging into Diorama.
50
51**Output:** `.starrod/build/assets.bin`
52
53**What it does:**
541. Compiles all project assets (maps, sprites, textures, etc.)
552. Compresses binary data using Yay0 compression
563. Writes to `.starrod/build/assets.bin`
57
58**Use cases:**
59- Testing asset compilation without creating a full distribution
60- Integration with custom build pipelines
61- Rapid iteration during development
62
63---
64
65## Diorama Management
66
67### Apply Diorama to ROM
68```bash
69java -jar StarRod.jar apply <pmdx-file> <rom-file> [output-rom]
70```
71
72Apply a Diorama package to a ROM file.
73
74**Arguments:**
75- `<pmdx-file>`: Path to the .diorama package
76- `<rom-file>`: Path to the base ROM (papermario.z64)
77- `[output-rom]`: Optional output path (defaults to modifying rom-file in-place)
78
79**Examples:**
80```bash
81# Apply to a copy
82java -jar StarRod.jar apply mymod.diorama baserom.z64 modded.z64
83
84# Apply in-place (modifies baserom.z64)
85java -jar StarRod.jar apply mymod.diorama baserom.z64
86```
87
88**Diorama Package Format:**
89A Diorama package is a TAR.GZ archive containing:
90- `project.kdl` - Project manifest with mod metadata
91- `target.json` - Target configuration (engine SHA, ROM addresses)
92- `assets.bin` - AssetsArchive binary
93
94**target.json example:**
95```json
96{
97 "papermario-dx": {
98 "engine_sha": "a1b2c3d4e5f6...",
99 "assets_archive_ROM_START": "0x1E40000"
100 }
101}
102```
103
104**What it does:**
1051. Extracts assets.bin from the Diorama package
1062. Copies the base ROM to the output location (if specified)
1073. Validates that the ROM is a compatible papermario-dx build
1084. Applies the mod using intelligent patching strategy (see below)
109
110**ROM Patching Strategy:**
111
112The patcher automatically detects if the mod already exists in the ROM (by project name):
113
114- **If mod exists and new version fits:** Replaces in-place for optimal ROM size
115- **If mod exists but new version is larger:** Removes old version, appends new one
116- **If mod doesn't exist:** Appends to the end of the chain
117
118This means you can repeatedly apply the same mod during development without the ROM growing unbounded. Each re-application replaces the previous version if possible.
119
120**Technical Details:**
121- Validates ROM has AssetsArchive chain (refuses vanilla PM64 ROMs)
122- Aligns data to 16-byte boundaries (N64 requirement)
123- Updates linked list to maintain chain integrity
124- Supports chaining multiple different mods
125
126### Inspect AssetsArchive
127```bash
128java -jar StarRod.jar inspect <archive-file>
129```
130
131Display the contents and metadata of an AssetsArchive file.
132
133**Example:**
134```bash
135java -jar StarRod.jar inspect .starrod/build/assets.bin
136```
137
138**Output:**
139```
140AssetsArchive Information:
141 Magic: MAPFS
142 Project: MyMod
143 File size: 245760 bytes
144
145Table of Contents:
146 Name Offset Comp. Size Decomp. Size
147 ----------------------------------------------------------------------------------------------------
148 kmr_20_shape.bin 184 12345 15000
149 kmr_20_collision.bin 12529 8192 10240
150 custom_texture.bin 20721 4096 4096
151 END DATA - - -
152
153 Total: 3 entries
154 Compressed: 24633 bytes
155 Decompressed: 29336 bytes
156 Compression: 84.0%
157```
158
159**Use cases:**
160- Debugging archive contents
161- Verifying compression ratios
162- Checking which assets are included
163- Inspecting downloaded Diorama packages
164
165---
166
167## AssetsArchive Format
168
169The AssetsArchive format is based on Paper Mario's internal "mapfs" filesystem:
170
171### Binary Structure
172```
173[Header: 32 bytes]
174 - Magic: "MAPFS " (6 bytes)
175 - Project name: (16 bytes, null-padded)
176 - Reserved: (10 bytes)
177
178[Table of Contents: N × 76 bytes]
179 For each entry:
180 - Name: (64 bytes, null-terminated)
181 - Data offset: (4 bytes, big-endian)
182 - Compressed size: (4 bytes, big-endian)
183 - Decompressed size: (4 bytes, big-endian)
184
185[Sentinel Entry: 76 bytes]
186 - Name: "END DATA\0"
187 - Next node offset: (4 bytes) - 0 = end of chain
188 - Compressed size: 0
189 - Decompressed size: 0
190
191[Data Section]
192 - Raw or Yay0-compressed binary data
193```
194
195### Compression
196- Files ≥64 bytes are compressed using Yay0 (LZSS variant)
197- Files <64 bytes stored uncompressed
198- Binary artifacts (BINARY, SHAPE, COLLISION types) are compressed
199- Headers and small files stored uncompressed
200
201### ROM Integration
202- AssetsArchive uses a linked list in ROM
203- Multiple mods can chain together
204- Default ROM address: 0x1E40000
205- Each node can point to the next via sentinel entry
206
207---
208
209## Automation Examples
210
211### CI/CD Build Pipeline
212```bash
213#!/bin/bash
214# Build and release a mod
215
216set -e
217
218# Build the Diorama package
219java -jar StarRod.jar pmdx
220
221# Verify the archive
222java -jar StarRod.jar inspect .starrod/build/assets.bin
223
224# Upload to release
225MOD_ID=$(grep 'id =' project.kdl | cut -d'"' -f2)
226cp .starrod/build/${MOD_ID}.diorama releases/
227```
228
229### Rapid Asset Testing
230```bash
231#!/bin/bash
232# Quick rebuild and inspect
233
234java -jar StarRod.jar archive
235java -jar StarRod.jar inspect .starrod/build/assets.bin
236```
237
238### Iterative Development
239```bash
240#!/bin/bash
241# Repeatedly apply your mod during development
242# The ROM won't grow each time - your mod gets replaced in-place
243
244while true; do
245 # Make changes to your project...
246 java -jar StarRod.jar pmdx
247 java -jar StarRod.jar apply mymod.diorama papermario-dx.z64 test.z64
248 # Test in emulator...
249done
250
251# Result: test.z64 stays roughly the same size because your mod
252# is replaced each iteration rather than appended
253```
254
255### Multi-Mod ROM Creation
256```bash
257#!/bin/bash
258# Apply multiple mods to a base ROM
259
260BASE_ROM="papermario.z64"
261OUTPUT_ROM="modded.z64"
262
263# Copy base
264cp "$BASE_ROM" "$OUTPUT_ROM"
265
266# Apply mods in sequence
267java -jar StarRod.jar apply mod1.diorama "$OUTPUT_ROM"
268java -jar StarRod.jar apply mod2.diorama "$OUTPUT_ROM"
269java -jar StarRod.jar apply mod3.diorama "$OUTPUT_ROM"
270
271echo "Multi-mod ROM created: $OUTPUT_ROM"
272```
273
274---
275
276## Exit Codes
277
278- `0`: Success
279- `1`: Error (build failed, file not found, etc.)
280
281---
282
283## Notes
284
285- All commands must be run from a valid project directory (except -HELP and -VERSION)
286- Paths can be relative or absolute
287- File extensions are important (.diorama, .z64, .bin)
288- Build output goes to `.starrod/build/` directory
289- ROM files are modified in-place unless an output path is specified