Snapshot of the Umamo working tree as it is

Uploaded as-is from /home/litruv/dev/vtsmaker/umamo on 2026-11-03. 1347 files.
Includes the uncommitted work in progress in :edit, :runtime, and :ui, and the
untracked files under module/edit/src/jvmAndroidMain/.

History is not carried over. The source repo is https://github.com/umamoorg/umamo.
This commit is contained in:
litruv
2026-11-03 18:20:25 +11:00
commit 8bd8fa7a0b
1347 changed files with 246161 additions and 0 deletions
+45
View File
@@ -0,0 +1,45 @@
// :cli (app/cli) — the headless diagnostic tool: dump / extract / atlas / convert / diff over cmo3,
// moc3, and source artwork files.
// JVM-only on purpose: it is an operator's tool, not a shipping app target. It deliberately avoids
// :ui (whose document layer drags in Compose via LiveParams) and :edit — everything it needs is the
// :interop conversion surface plus :render's space/texture helpers.
plugins {
alias(libs.plugins.kotlinMultiplatform)
}
kotlin {
jvmToolchain(21)
jvm()
sourceSets {
jvmMain {
dependencies {
// :interop api-exposes :format and :runtime, so those come transitively.
implementation(project(":interop"))
// restMeshesToCanvasSpace / canvasToParentSpaceFor and the atlas texture helpers.
implementation(project(":render"))
}
}
}
}
// A hand-registered JavaExec rather than the application plugin: the compose.desktop application
// block is the repo's only other runnable and is not wanted here. Only file collections are
// captured (never the Project), keeping the task configuration-cache safe; `--args` works through
// JavaExec's built-in @Option.
val cliMainCompilation = kotlin.jvm().compilations.getByName("main")
val repositoryRoot = rootDir
tasks.register<JavaExec>("run") {
group = "application"
description = "Runs the Umamo diagnostic CLI; pass arguments with --args=\"dump model.moc3\"."
mainClass.set("org.umamo.cli.MainKt")
classpath(cliMainCompilation.output.allOutputs, cliMainCompilation.runtimeDependencyFiles)
// Relative file arguments should resolve against the repo root the operator invoked from, not
// this subproject's directory (JavaExec's default).
workingDir = repositoryRoot
// The atlas packer holds every source layer's pixels plus the pages it composes, and a real
// document is hundreds of megabytes of raster before a single page is allocated. The JVM
// default (a quarter of RAM) is not something to leave to the operator's machine.
maxHeapSize = "6g"
}
@@ -0,0 +1,353 @@
package org.umamo.cli
import org.umamo.format.art.SourceArt
import org.umamo.format.art.SourceLayer
import org.umamo.format.art.SourceLayerKind
import org.umamo.format.art.isEffectivelyVisible
import org.umamo.format.atlas.AtlasPackItem
import org.umamo.format.atlas.AtlasPackOptions
import org.umamo.format.atlas.AtlasPackPlacement
import org.umamo.format.atlas.AtlasPackResult
import org.umamo.format.atlas.atlasPackItems
import org.umamo.format.atlas.packAtlas
import org.umamo.format.png.PngCodec
import org.umamo.format.raster.RasterImage
import java.io.File
/*
* The atlas subcommand: pack a source artwork document's layers into texture atlas pages.
*
* The packer's standalone proof and inspection surface, beside the editor's own Repack Atlas command
* (document.repackAtlas): it writes the pages, reports every placement, and checks each packed tile
* back out of the page it landed on before claiming success.
*/
/** Canvas pixels past which the preview composite is skipped rather than allocated. */
private const val PREVIEW_PIXEL_CAP = 128_000_000
/**
* Runs `atlas <file> [<directory>] [options]`.
*
* Output lands in a NEW subdirectory named after the input, created under the given directory
* (default: the input file's own directory), matching how `extract` keeps its output from mixing
* into a folder that already holds other files.
*
* @param List arguments The subcommand's arguments.
* @return Int The exit code; 1 when a packed tile fails to read back out of its page.
*/
internal fun runAtlas(arguments: List<String>): Int {
val parsed =
parseArguments(
arguments,
knownFlags = setOf("--rotate", "--visible-only", "--no-shrink", "--preview"),
knownOptions = setOf("--page-size", "--gutter", "--extrude"),
)
if (parsed.positionals.isEmpty() || parsed.positionals.size > 2) {
throw CliUsageException(
"Usage: atlas <file> [<directory>] [--page-size=N] [--gutter=N] [--extrude=N] " +
"[--rotate] [--visible-only] [--no-shrink] [--preview]",
)
}
val loaded = loadInput(parsed.positionals[0])
if (loaded !is LoadedInput.SourceArtInput) {
throw CliUsageException("Atlas applies to source artwork only (psd, clip, kra, or a flat raster)")
}
val gutter = parsed.intOption("--gutter", 2)
val options =
AtlasPackOptions(
maxPageSize = parsed.intOption("--page-size", 4096),
gutter = gutter,
extrude = parsed.intOption("--extrude", minOf(2, gutter)),
allowRotation = "--rotate" in parsed.flags,
shrinkPages = "--no-shrink" !in parsed.flags,
)
val art = loaded.art
val visibleOnly = "--visible-only" in parsed.flags
val include: (SourceLayer) -> Boolean = { layer ->
layer.kind == SourceLayerKind.Raster && (!visibleOnly || art.isEffectivelyVisible(layer))
}
val includedLayers = art.layers.filter(include)
val items = art.atlasPackItems(include)
if (items.isEmpty()) {
throw CliUsageException("${loaded.file.name} has no raster layers to pack")
}
val nonRasterCount = art.layers.count { layer -> layer.kind != SourceLayerKind.Raster }
if (nonRasterCount > 0) {
System.err.println("Note: $nonRasterCount non-raster layer(s) carry no pixels and were not packed.")
}
println("Packing ${items.size} layer(s) of ${loaded.file.name} (${art.widthPx}x${art.heightPx} canvas)")
val result = packAtlas(items, options)
val outputDirectory = resolveOutputDirectory(loaded.file, parsed.positionals.getOrNull(1))
outputDirectory.mkdirs()
writePages(result, outputDirectory)
writeReport(result, includedLayers, items, options, loaded.file, outputDirectory)
reportSkips(result)
if ("--preview" in parsed.flags) {
writePreview(art, includedLayers, items, result, outputDirectory)
}
val mismatches = verifyTiles(items, result)
if (mismatches.isNotEmpty()) {
System.err.println("VERIFY FAILED: ${mismatches.size} tile(s) do not match their source pixels:")
mismatches.take(10).forEach { message -> System.err.println(" $message") }
return 1
}
println("Verified ${result.placements.size}/${result.placements.size} tiles byte-exact")
return 0
}
/**
* Resolves the output subdirectory, named after the input file.
*
* @param File inputFile The source artwork file.
* @param String? parentDirectory The caller's directory argument, when given.
* @return File The directory the pages and report write into.
*/
private fun resolveOutputDirectory(inputFile: File, parentDirectory: String?): File {
val parent = if (parentDirectory != null) File(parentDirectory) else (inputFile.parentFile ?: File("."))
val directory = File(parent, inputFile.nameWithoutExtension)
if (directory.exists()) {
System.err.println("Note: ${directory.path} already exists; its matching files will be overwritten.")
}
return directory
}
/**
* Encodes and writes every packed page.
*
* @param AtlasPackResult result The packing outcome.
* @param File outputDirectory The directory to write into.
*/
private fun writePages(result: AtlasPackResult, outputDirectory: File) {
for ((pageIndex, page) in result.pages.withIndex()) {
val target = File(outputDirectory, "page_${pageIndex.toString().padStart(2, '0')}.png")
val bytes = PngCodec.write(page)
target.writeBytes(bytes)
val occupancy = (result.pageOccupancy(pageIndex) * 100f).toInt()
println("Wrote ${target.path} (${page.width}x${page.height}, $occupancy% occupancy, ${bytes.size} bytes)")
}
}
/**
* Writes the placement report: the options the pack ran with, one line per placement, then the skips.
*
* @param AtlasPackResult result The packing outcome.
* @param List layers The layers that were offered to the packer, in the same order as [items].
* @param List items The pack items, parallel to [layers].
* @param AtlasPackOptions options The options the pack ran with.
* @param File inputFile The source artwork file.
* @param File outputDirectory The directory to write into.
*/
private fun writeReport(
result: AtlasPackResult,
layers: List<SourceLayer>,
items: List<AtlasPackItem>,
options: AtlasPackOptions,
inputFile: File,
outputDirectory: File,
) {
val layerNameByKey = items.indices.associate { itemIndex -> items[itemIndex].key to layers[itemIndex].name }
val target = File(outputDirectory, "placements.txt")
val report = StringBuilder()
report.appendLine("#atlas placements for ${inputFile.name}")
report.appendLine(
"#options pageSize=${options.maxPageSize} gutter=${options.gutter} extrude=${options.extrude} " +
"rotate=${options.allowRotation} shrink=${options.shrinkPages}",
)
for ((pageIndex, page) in result.pages.withIndex()) {
report.appendLine(
"#page $pageIndex ${page.width}x${page.height} ${(result.pageOccupancy(pageIndex) * 100f).toInt()}% occupancy",
)
}
report.appendLine("#page\tx\ty\twidth\theight\tturns\ttrimX\ttrimY\tkey\tname")
for (placement in result.placements) {
report.appendLine(
listOf(
placement.pageIndex,
placement.pageX,
placement.pageY,
placement.pageWidth,
placement.pageHeight,
placement.quarterTurns,
placement.trimLeft,
placement.trimTop,
placement.key,
layerNameByKey[placement.key].orEmpty(),
).joinToString("\t"),
)
}
for (skip in result.skipped) {
report.appendLine("#skipped\t${skip.reason}\t${skip.key}\t${layerNameByKey[skip.key].orEmpty()}")
}
target.writeText(report.toString())
println("Wrote ${target.path} (${result.placements.size} placements, ${result.skipped.size} skipped)")
}
/**
* Prints the skip tally to stderr, grouped by reason.
*
* A page that looks right while several layers quietly went missing is this stage's characteristic
* failure, so the skips are reported every run rather than only living in the written report.
*
* @param AtlasPackResult result The packing outcome.
*/
private fun reportSkips(result: AtlasPackResult) {
if (result.skipped.isEmpty()) {
return
}
for ((reason, skips) in result.skipped.groupBy { skip -> skip.reason }) {
System.err.println("Note: ${skips.size} layer(s) not packed - $reason")
}
}
/**
* Reads every packed tile back out of its page and compares it to the source pixels.
*
* This is the command's reason to exist: the atlas is a repackable indirection over the source art,
* so a page that does not reproduce the art it was built from is worthless however good it looks.
* The page-coordinate mapping ([pagePixelOf]) is written out in this file rather than shared with the
* packer, so a wrong rotation convention cannot agree with itself.
*
* @param List items The tiles that were packed.
* @param AtlasPackResult result The packing outcome.
* @return List One message per mismatching tile, empty when every tile matched.
*/
private fun verifyTiles(items: List<AtlasPackItem>, result: AtlasPackResult): List<String> {
val itemsByKey = items.associateBy { item -> item.key }
val mismatches = mutableListOf<String>()
for (placement in result.placements) {
val item = itemsByKey.getValue(placement.key)
val page = result.pages[placement.pageIndex]
var mismatch: String? = null
for (tileY in 0 until placement.trimHeight) {
for (tileX in 0 until placement.trimWidth) {
val (pageX, pageY) = pagePixelOf(placement, tileX, tileY)
val sourceOffset = ((placement.trimTop + tileY) * item.width + placement.trimLeft + tileX) * 4
val pageOffset = (pageY * page.width + pageX) * 4
for (channelIndex in 0 until 4) {
if (item.rgba[sourceOffset + channelIndex] != page.rgba[pageOffset + channelIndex]) {
mismatch = "'${placement.key}' tile pixel ($tileX, $tileY) at page ($pageX, $pageY)"
break
}
}
if (mismatch != null) {
break
}
}
if (mismatch != null) {
break
}
}
mismatch?.let { message -> mismatches.add(message) }
}
return mismatches
}
/**
* The page pixel a trimmed tile's pixel lands on under its placement, independent of the packer's
* own composition so the two can disagree; one copy serves both the byte check and the preview so
* those two cannot.
*
* @param AtlasPackPlacement placement Where the tile sits on its page.
* @param Int tileX The pixel's x within the trim.
* @param Int tileY The pixel's y within the trim.
* @return Pair<Int, Int> The page (x, y).
*/
private fun pagePixelOf(placement: AtlasPackPlacement, tileX: Int, tileY: Int): Pair<Int, Int> =
if (placement.quarterTurns == 0) {
(placement.pageX + tileX) to (placement.pageY + tileY)
} else {
(placement.pageX + tileY) to (placement.pageY + placement.trimWidth - 1 - tileX)
}
/**
* Composites the packed layers back onto a canvas-sized image, sampling from the PAGES.
*
* The byte check proves the pages carry the right pixels; this is what a human looks at to see that
* the placements also mean the right thing. Blend modes and layer opacity are ignored - it is a
* source-over stack, not a compositor - so a document leaning on them will not match its own
* application's render, which is expected rather than a packing fault.
*
* @param SourceArt art The source document, for canvas size and layer positions.
* @param List layers The layers that were offered to the packer, parallel to [items].
* @param List items The pack items, parallel to [layers].
* @param AtlasPackResult result The packing outcome.
* @param File outputDirectory The directory to write into.
*/
private fun writePreview(
art: SourceArt,
layers: List<SourceLayer>,
items: List<AtlasPackItem>,
result: AtlasPackResult,
outputDirectory: File,
) {
if (art.widthPx.toLong() * art.heightPx.toLong() > PREVIEW_PIXEL_CAP) {
System.err.println("Note: ${art.widthPx}x${art.heightPx} canvas exceeds the preview cap; preview skipped.")
return
}
val placementByKey = result.placements.associateBy { placement -> placement.key }
val canvas = ByteArray(art.widthPx * art.heightPx * 4)
// Source-over from the bottom up: order is top-most first, so the highest order draws first.
for (layerIndex in layers.indices.sortedByDescending { layerIndex -> layers[layerIndex].order }) {
val placement = placementByKey[items[layerIndex].key] ?: continue
drawPlacementOntoCanvas(canvas, art.widthPx, art.heightPx, layers[layerIndex], placement, result)
}
val target = File(outputDirectory, "preview.png")
val bytes = PngCodec.write(RasterImage(art.widthPx, art.heightPx, canvas))
target.writeBytes(bytes)
println("Wrote ${target.path} (${art.widthPx}x${art.heightPx} recomposite from the packed pages, ${bytes.size} bytes)")
}
/**
* Draws one placed layer onto the preview canvas, reading its pixels out of the atlas page.
*
* @param ByteArray canvas The canvas buffer, RGBA8888 straight alpha.
* @param Int canvasWidth The canvas width in pixels.
* @param Int canvasHeight The canvas height in pixels.
* @param SourceLayer layer The layer being drawn, for its canvas position.
* @param AtlasPackPlacement placement Where its pixels sit on a page.
* @param AtlasPackResult result The packing outcome holding the pages.
*/
private fun drawPlacementOntoCanvas(
canvas: ByteArray,
canvasWidth: Int,
canvasHeight: Int,
layer: SourceLayer,
placement: AtlasPackPlacement,
result: AtlasPackResult,
) {
val page = result.pages[placement.pageIndex]
for (tileY in 0 until placement.trimHeight) {
val canvasY = layer.bounds.top + placement.trimTop + tileY
if (canvasY < 0 || canvasY >= canvasHeight) {
continue
}
for (tileX in 0 until placement.trimWidth) {
val canvasX = layer.bounds.left + placement.trimLeft + tileX
if (canvasX < 0 || canvasX >= canvasWidth) {
continue
}
val (pageX, pageY) = pagePixelOf(placement, tileX, tileY)
val pageOffset = (pageY * page.width + pageX) * 4
val canvasOffset = (canvasY * canvasWidth + canvasX) * 4
val sourceAlpha = (page.rgba[pageOffset + 3].toInt() and 0xFF) / 255f
if (sourceAlpha <= 0f) {
continue
}
val destinationAlpha = (canvas[canvasOffset + 3].toInt() and 0xFF) / 255f
val outAlpha = sourceAlpha + destinationAlpha * (1f - sourceAlpha)
for (channelIndex in 0 until 3) {
val sourceChannel = (page.rgba[pageOffset + channelIndex].toInt() and 0xFF) / 255f
val destinationChannel = (canvas[canvasOffset + channelIndex].toInt() and 0xFF) / 255f
val blended =
(sourceChannel * sourceAlpha + destinationChannel * destinationAlpha * (1f - sourceAlpha)) / outAlpha
canvas[canvasOffset + channelIndex] = (blended * 255f + 0.5f).toInt().coerceIn(0, 255).toByte()
}
canvas[canvasOffset + 3] = (outAlpha * 255f + 0.5f).toInt().coerceIn(0, 255).toByte()
}
}
}
@@ -0,0 +1,244 @@
package org.umamo.cli
import org.umamo.format.FormatRegistry
import org.umamo.format.art.ArtReader
import org.umamo.format.art.SourceArt
import org.umamo.format.cmo3.Cmo3
import org.umamo.format.cmo3.Cmo3Model
import org.umamo.format.cmo3.model.custom.CModelSource
import org.umamo.format.moc3.Moc3
import org.umamo.format.moc3.MocDocument
import org.umamo.format.moc3.json.Cdi3Json
import org.umamo.format.moc3.json.Model3Json
import org.umamo.format.raster.RasterCodec
import org.umamo.format.raster.rasterToSourceArt
import org.umamo.interop.cmo3.Cmo3Import
import org.umamo.interop.moc3.Moc3Sidecars
import org.umamo.interop.moc3.import.Moc3Import
import org.umamo.render.restMeshesToCanvasSpace
import org.umamo.runtime.model.PuppetModel
import java.io.File
import java.util.Locale
/*
* Input routing shared by every subcommand: read a file, detect its format through the same
* FormatRegistry the app uses, and (for moc3) discover the sibling family files through the
* model3.json manifest.
*/
/** A loaded input file, branched by detected format. */
internal sealed interface LoadedInput {
/** A CMO3 editor document. */
class Cmo3Input(val model: Cmo3Model, val bytes: ByteArray) : LoadedInput
/** A MOC3 runtime document plus whatever family files sat beside it. */
class Moc3Input(val document: MocDocument, val family: Moc3Family) : LoadedInput
/**
* Layered or flat source artwork: PSD, CLIP, KRA, or any of the flat raster formats read as a
* single-layer document. It carries no rig - there is no source-art to PuppetModel bridge yet
* (pipeline Phase E) - so only artwork-side commands accept it.
*/
class SourceArtInput(val art: SourceArt, val file: File) : LoadedInput
}
/**
* The MOC3 family files discovered around a moc: the manifest (when present), the display-info
* sidecar, the texture files the manifest references, and the pass-through sidecar texts.
*
* @property File mocFile The .moc3 file itself.
* @property Model3Json? manifest The parsed model3.json, or null when none was found.
* @property Cdi3Json? displayInfo The parsed cdi3.json, or null when absent.
* @property List textureFiles The manifest's texture files, resolved against its directory.
* @property List sidecars Physics/pose/userdata texts, carried through verbatim.
*/
internal class Moc3Family(
val mocFile: File,
val manifest: Model3Json?,
val displayInfo: Cdi3Json?,
val textureFiles: List<File>,
val sidecars: List<Moc3Sidecars.PassThroughSidecar>,
)
/**
* Reads and format-detects one input file. A .model3.json path is accepted as a moc3 input, with
* the MOC3 resolved through the manifest's own file reference.
*
* @param String path The input file path.
* @return LoadedInput The loaded, format-branched input.
*/
internal fun loadInput(path: String): LoadedInput {
val inputFile = File(path)
if (!inputFile.isFile) {
throw CliUsageException("No such file: $path")
}
if (inputFile.name.lowercase(Locale.ROOT).endsWith(".model3.json")) {
val manifest = Moc3.readModel3(inputFile.readText())
val mocFile = File(inputFile.parentFile, manifest.fileReferences.moc)
if (!mocFile.isFile) {
throw CliUsageException("Manifest references a missing MOC3: ${mocFile.path}")
}
return loadMoc3(mocFile, manifestFile = inputFile, manifest = manifest)
}
val bytes = inputFile.readBytes()
return when (val codec = FormatRegistry.detect(bytes, inputFile.name)) {
Cmo3 -> LoadedInput.Cmo3Input(Cmo3.read(bytes), bytes)
Moc3 -> loadMoc3(inputFile, manifestFile = null, manifest = null)
is ArtReader -> LoadedInput.SourceArtInput(codec.read(bytes), inputFile)
// A flat raster becomes a one-layer document, which is what makes `atlas cover.png` mean
// something rather than being rejected for lacking layers.
is RasterCodec -> LoadedInput.SourceArtInput(rasterToSourceArt(codec.read(bytes), inputFile.nameWithoutExtension), inputFile)
else -> throw CliUsageException("Unsupported input format: $path (expected cmo3, moc3, model3.json, or source artwork)")
}
}
/**
* Loads a moc3 and discovers its family. Without an explicit manifest the sibling
* `<basename>.model3.json` is tried first, then any manifest in the directory whose moc reference
* names this file.
*
* @param File mocFile The .moc3 file.
* @param File? manifestFile The manifest file, when the caller already has it.
* @param Model3Json? manifest The parsed manifest, when the caller already has it.
* @return LoadedInput The moc3 input with its family.
*/
private fun loadMoc3(mocFile: File, manifestFile: File?, manifest: Model3Json?): LoadedInput.Moc3Input {
val document = Moc3.read(mocFile.readBytes())
val resolvedManifestFile =
manifestFile
?: File(mocFile.parentFile, Moc3Sidecars.basenameFor(mocFile.name) + ".model3.json").takeIf { candidate -> candidate.isFile }
?: mocFile.parentFile
?.listFiles { _, name -> name.lowercase(Locale.ROOT).endsWith(".model3.json") }
?.firstOrNull { candidate ->
runCatching { Moc3.readModel3(candidate.readText()).fileReferences.moc == mocFile.name }.getOrDefault(false)
}
val resolvedManifest = manifest ?: resolvedManifestFile?.let { file -> Moc3.readModel3(file.readText()) }
if (resolvedManifest == null) {
return LoadedInput.Moc3Input(document, Moc3Family(mocFile, null, null, emptyList(), emptyList()))
}
val manifestDirectory = resolvedManifestFile!!.parentFile
val references = resolvedManifest.fileReferences
// Manifest reference first, then the sibling-by-basename fallback the app's document loader
// uses - a model3 without a DisplayInfo entry otherwise converts nameless, and the export then
// writes parameter ids where Cubism expects display names.
val displayInfo =
listOfNotNull(references.displayInfo, "${mocFile.nameWithoutExtension}.cdi3.json")
.distinct()
.firstNotNullOfOrNull { reference ->
File(manifestDirectory, reference)
.takeIf { file -> file.isFile }
?.let { file -> runCatching { Moc3.readCdi3(file.readText()) }.getOrNull() }
}
val textureFiles = references.textures.map { reference -> File(manifestDirectory, reference) }
val sidecars =
buildList {
fun passThrough(kind: Moc3Sidecars.SidecarKind, reference: String?) {
val file = reference?.let { relative -> File(manifestDirectory, relative) } ?: return
if (file.isFile) {
add(Moc3Sidecars.PassThroughSidecar(kind, file.name, file.readText()))
}
}
passThrough(Moc3Sidecars.SidecarKind.Physics, references.physics)
passThrough(Moc3Sidecars.SidecarKind.Pose, references.pose)
passThrough(Moc3Sidecars.SidecarKind.UserData, references.userData)
}
return LoadedInput.Moc3Input(document, Moc3Family(mocFile, resolvedManifest, displayInfo, textureFiles, sidecars))
}
/**
* Imports a loaded input to the runtime PuppetModel - the exact import path the editor uses.
*
* A MOC3-origin puppet gets restMeshesToCanvasSpace (its rest meshes arrive in parent-deformer
* space); a CMO3-origin one authors directly in canvas pixels and must NOT be rebased.
*
* @param LoadedInput loaded The loaded input.
* @return PuppetModel The imported puppet, in canvas space.
*/
internal fun importPuppet(loaded: LoadedInput): PuppetModel =
when (loaded) {
is LoadedInput.Cmo3Input -> Cmo3Import.fromModelSource(loaded.model.root as CModelSource)
is LoadedInput.Moc3Input -> restMeshesToCanvasSpace(Moc3Import.fromMocDocument(loaded.document, loaded.family.displayInfo))
is LoadedInput.SourceArtInput ->
throw CliUsageException(
"${loaded.file.name} is source artwork, which carries no rig; try `atlas` (a source-art to " +
"PuppetModel bridge is pipeline Phase E and does not exist yet)",
)
}
/**
* One command line split into positionals, boolean flags, and valued options.
*
* @property List positionals The non-flag arguments, in order.
* @property Set flags The boolean flags present, with their leading dashes.
* @property Map options The `--key=value` options, keyed with their leading dashes.
*/
internal class CliArguments(
val positionals: List<String>,
val flags: Set<String>,
val options: Map<String, String>,
) {
/**
* Reads one valued option as an integer.
*
* @param String name The option name, with its leading dashes.
* @param Int defaultValue The value to use when the option is absent.
* @return Int The parsed value.
*/
fun intOption(name: String, defaultValue: Int): Int {
val raw = options[name] ?: return defaultValue
return raw.toIntOrNull() ?: throw CliUsageException("$name expects a whole number, got '$raw'")
}
}
/**
* Splits a command line, rejecting anything the caller did not declare.
*
* Unknown flags are a usage error rather than being ignored, so a mistyped option cannot silently
* produce output the operator believes was generated some other way.
*
* @param List arguments The subcommand's raw arguments.
* @param Set knownFlags The boolean flags this subcommand accepts, with leading dashes.
* @param Set knownOptions The `--key=value` options this subcommand accepts, with leading dashes.
* @return CliArguments The split command line.
*/
internal fun parseArguments(arguments: List<String>, knownFlags: Set<String>, knownOptions: Set<String>): CliArguments {
val positionals = mutableListOf<String>()
val flags = mutableSetOf<String>()
val options = mutableMapOf<String, String>()
for (argument in arguments) {
if (!argument.startsWith("--")) {
positionals.add(argument)
continue
}
val separatorIndex = argument.indexOf('=')
if (separatorIndex < 0) {
if (argument !in knownFlags) {
throw CliUsageException("unknown flag '$argument'")
}
flags.add(argument)
continue
}
val name = argument.substring(0, separatorIndex)
if (name !in knownOptions) {
throw CliUsageException("unknown option '$name'")
}
options[name] = argument.substring(separatorIndex + 1)
}
return CliArguments(positionals, flags, options)
}
/**
* Formats a float like C's printf %.6g (what dump_model.c prints), so dump output stays diffable
* against the relive harness. Java's %g keeps trailing zeros where C strips them, hence the trim.
*
* @param Float value The value to format.
* @return String The %.6g-formatted text with C's trailing-zero trimming.
*/
internal fun formatSixSignificant(value: Float): String {
val raw = String.format(Locale.ROOT, "%.6g", value.toDouble())
val exponentIndex = raw.indexOfFirst { character -> character == 'e' || character == 'E' }
val mantissa = if (exponentIndex >= 0) raw.substring(0, exponentIndex) else raw
val exponent = if (exponentIndex >= 0) raw.substring(exponentIndex) else ""
val trimmed = if (mantissa.contains('.')) mantissa.trimEnd('0').trimEnd('.') else mantissa
return trimmed + exponent
}
@@ -0,0 +1,172 @@
package org.umamo.cli
import org.umamo.format.cmo3.Cmo3
import org.umamo.format.moc3.Moc3
import org.umamo.format.png.PngCodec
import org.umamo.interop.ExportReport
import org.umamo.interop.cmo3.Cmo3Conversion
import org.umamo.interop.cmo3.cmo3AtlasPages
import org.umamo.interop.describeExportNotice
import org.umamo.interop.moc3.Moc3Sidecars
import org.umamo.render.PuppetTextures
import org.umamo.render.UndecodablePagePolicy
import org.umamo.render.buildPuppetTextures
import org.umamo.render.canvasToParentSpaceFor
import org.umamo.render.encodeAtlasPng
import org.umamo.render.withTexturePagesFrom
import java.io.File
import java.util.Locale
import kotlin.random.Random
/*
* The convert subcommand: cmo3/moc3 resaves and cross-format conversions, replacing the old
* Cmo3ResaveDumpTest -Dcmo3.resave workflow.
*/
/**
* Runs `convert <in> <out>`, picking the direction from the input's detected format and the output
* path's extension.
*
* @param List arguments The subcommand's arguments.
* @return Int The exit code.
*/
internal fun runConvert(arguments: List<String>): Int {
if (arguments.size != 2) {
throw CliUsageException("Usage: convert <in> <out>")
}
val loaded = loadInput(arguments[0])
val outputFile = File(arguments[1])
val outputExtension = outputFile.name.substringAfterLast('.', "").lowercase(Locale.ROOT)
outputFile.parentFile?.mkdirs()
when {
loaded is LoadedInput.Cmo3Input && outputExtension == "cmo3" -> {
// An unedited graph re-emits its main.xml byte-identically; only the CAFF wrapper differs.
Cmo3.write(loaded.model, outputFile)
println("Resaved cmo3 -> ${outputFile.path} (${outputFile.length()} bytes)")
}
loaded is LoadedInput.Moc3Input && outputExtension == "moc3" -> {
outputFile.writeBytes(Moc3.write(loaded.document))
println("Rebaked moc3 -> ${outputFile.path} (${outputFile.length()} bytes)")
println("Note: a rebake is a fresh synthesis, NOT byte-identical to the source by design")
}
loaded is LoadedInput.Cmo3Input && outputExtension == "moc3" -> {
convertCmo3ToMoc3Family(loaded, outputFile)
}
loaded is LoadedInput.Moc3Input && outputExtension == "cmo3" -> {
convertMoc3ToCmo3(loaded, outputFile)
}
else -> throw CliUsageException("Unsupported conversion: ${arguments[0]} -> ${outputFile.name}")
}
return 0
}
/**
* Lowers a CMO3 document to the full MOC3 family (moc3 + model3.json + cdi3.json + atlas textures)
* next to [outputFile].
*
* The two mandatory pre-steps mirror the app's own export path: the puppet's drawables arrive on
* the -1 texture-page sentinel (CMO3 binds textures through the layered-art web, not a page index),
* so withTexturePagesFrom must land real pages before the lowering can name them.
*
* @param LoadedInput.Cmo3Input loaded The cmo3 input.
* @param File outputFile The target .moc3 path; the family lands beside it.
*/
private fun convertCmo3ToMoc3Family(loaded: LoadedInput.Cmo3Input, outputFile: File) {
val basename = Moc3Sidecars.basenameFor(outputFile.name)
val importedPuppet = importPuppet(loaded)
val modelSource = (loaded.model.root as org.umamo.format.cmo3.model.custom.CModelSource)
val pageSet = cmo3AtlasPages(modelSource) { imageResource -> loaded.model.extractLayerPng(imageResource) }
// Skip matches the editor's CMO3 loader: a page that will not decode drops rather than failing the
// whole conversion, and Skip never returns null, so the fallback is unreachable.
val textures =
buildPuppetTextures(
pageSet.pageBytes,
pageSet.atlasIndexByDrawableId,
pageSet.premultipliedAlpha,
UndecodablePagePolicy.Skip,
) ?: PuppetTextures(emptyList(), emptyMap(), pageSet.premultipliedAlpha)
val puppet = withTexturePagesFrom(importedPuppet, textures)
val pages =
textures.atlases.mapIndexed { pageIndex, atlas ->
Moc3Sidecars.AtlasPage(
fileName = String.format(Locale.ROOT, "%s.%d/texture_%02d.png", basename, atlas.width, pageIndex),
bytes = encodeAtlasPng(atlas),
)
}
val bundle =
Moc3Sidecars.bundle(
puppet = puppet,
basename = basename,
pages = pages,
canvasToParentSpace = canvasToParentSpaceFor(puppet),
)
// Overwrites without confirmation.
val outputDirectory = outputFile.parentFile ?: File(".")
for (bundleFile in bundle.files) {
val target = File(outputDirectory, bundleFile.name)
target.parentFile?.mkdirs()
target.writeBytes(bundleFile.bytes)
println("Wrote ${target.path} (${bundleFile.bytes.size} bytes)")
}
reportNotices(bundle.report)
}
/**
* Synthesizes a fresh CMO3 from a MOC3-origin document. The atlas pages come from the manifest's
* texture files; without a manifest the conversion proceeds textureless with a warning. A
* MissingSourceArt notice is always reported - the pages are atlas copies, not the original
* layered source art.
*
* @param LoadedInput.Moc3Input loaded The moc3 input with its discovered family.
* @param File outputFile The target .cmo3 path.
*/
private fun convertMoc3ToCmo3(loaded: LoadedInput.Moc3Input, outputFile: File) {
val puppet = importPuppet(loaded)
val presentTextureFiles = loaded.family.textureFiles.filter { textureFile -> textureFile.isFile }
if (loaded.family.manifest == null) {
System.err.println("Warning: no model3.json manifest found beside ${loaded.family.mocFile.name}; converting textureless")
} else if (presentTextureFiles.size < loaded.family.textureFiles.size) {
System.err.println("Warning: ${loaded.family.textureFiles.size - presentTextureFiles.size} manifest texture(s) missing on disk")
}
val pages =
presentTextureFiles.map { textureFile ->
val pngBytes = textureFile.readBytes()
val decoded = PngCodec.read(pngBytes)
Cmo3Conversion.AtlasPage(pngBytes = pngBytes, width = decoded.width, height = decoded.height)
}
val result =
Cmo3Conversion.freshCmo3(
puppet = puppet,
pages = pages,
pageIndexByDrawableId = loaded.document.artMeshes.associate { artMesh -> artMesh.id to artMesh.textureIndex },
modelName = outputFile.name.removeSuffix(".cmo3"),
nowMillis = System.currentTimeMillis(),
obfuscateKey = Random.nextInt(),
)
// Overwrites without confirmation.
Cmo3.write(result.model, outputFile)
println("Wrote ${outputFile.path} (${outputFile.length()} bytes)")
reportNotices(result.report)
}
/**
* Prints an export report's notices to stderr - advisory, never fatal. Each line is the same one the
* editor's log carries for that notice, so a report reads alike whichever tool wrote the file.
*
* @param ExportReport report The lowering's report.
*/
private fun reportNotices(report: ExportReport) {
if (report.isEmpty) {
return
}
System.err.println("Export notices (${report.notices.size}):")
for (notice in report.notices) {
System.err.println(" ${describeExportNotice(notice)}")
}
}
@@ -0,0 +1,94 @@
package org.umamo.cli
import org.umamo.interop.EntityDiff
import org.umamo.interop.GlueDiff
import org.umamo.interop.diffPuppetModels
import org.umamo.runtime.model.DeformerId
import org.umamo.runtime.model.DrawableId
import org.umamo.runtime.model.ParameterGroupId
import org.umamo.runtime.model.ParameterId
import org.umamo.runtime.model.PartId
/*
* The diff subcommand: the semantic per-entity difference between two models, through the same
* diffPuppetModels the CMO3 export reconcile dispatches on.
*/
/**
* Runs `diff <a> <b>`: imports both files (either format, both normalized to canvas space by the
* import path) and prints the per-category difference. Exit stays 0 either way - a diff is a
* report, not a failure.
*
* @param List arguments The subcommand's arguments.
* @return Int The exit code.
*/
internal fun runDiff(arguments: List<String>): Int {
if (arguments.size != 2) {
throw CliUsageException("Usage: diff <a> <b>")
}
val baseline = importPuppet(loadInput(arguments[0]))
val edited = importPuppet(loadInput(arguments[1]))
val diff = diffPuppetModels(baseline, edited)
if (diff.isEmpty) {
println("identical")
return 0
}
printCategory("parameters", diff.parameters)
printCategory("parameterGroups", diff.parameterGroups)
printCategory("parts", diff.parts)
printCategory("deformers", diff.deformers)
printCategory("drawables", diff.drawables)
if (diff.glues.isNotEmpty()) {
println("[glues]")
for (glueDiff in diff.glues) {
val key = "${glueDiff.meshA.raw}~${glueDiff.meshB.raw}#${glueDiff.ordinal}"
when (glueDiff) {
is GlueDiff.Created -> println("+ $key")
is GlueDiff.Deleted -> println("- $key")
is GlueDiff.Changed -> println("~ $key ${glueDiff.fields.sorted()}")
}
}
}
if (diff.document.isNotEmpty()) {
println("[document]")
println("~ ${diff.document.sorted()}")
}
return 0
}
/**
* Prints one entity category's diffs: `+ id` created, `- id` deleted, `~ id [FIELDS]` changed.
*
* @param String label The category heading.
* @param List diffs The category's entries (skipped entirely when empty).
*/
private fun <TId, TField : Comparable<TField>> printCategory(label: String, diffs: List<EntityDiff<TId, TField>>) {
if (diffs.isEmpty()) {
return
}
println("[$label]")
for (entityDiff in diffs) {
when (entityDiff) {
is EntityDiff.Created -> println("+ ${formatEntityId(entityDiff.id)}")
is EntityDiff.Deleted -> println("- ${formatEntityId(entityDiff.id)}")
is EntityDiff.Changed -> println("~ ${formatEntityId(entityDiff.id)} ${entityDiff.fields.sorted()}")
}
}
}
/**
* The bare id string of a typed entity id - the value-class toString ("PartId(raw=...)") is noise
* in a report meant for humans and diff scripts.
*
* @param Any? id The typed entity id.
* @return String The raw id text.
*/
private fun formatEntityId(id: Any?): String =
when (id) {
is ParameterId -> id.raw
is ParameterGroupId -> id.raw
is PartId -> id.raw
is DeformerId -> id.raw
is DrawableId -> id.raw
else -> id.toString()
}
@@ -0,0 +1,249 @@
package org.umamo.cli
import org.umamo.format.art.SourceLayerKind
import org.umamo.format.art.analyzeAlpha
import org.umamo.format.cmo3.Cmo3Model
import org.umamo.format.cmo3.caff.CaffArchive
import org.umamo.format.cmo3.serialize.ModelDocument
import org.umamo.format.moc3.MocDocument
import org.umamo.format.moc3.moc.MocCodec
import org.umamo.format.moc3.moc.Section
import org.umamo.runtime.model.PuppetModel
/*
* The dump subcommand: human-readable (and, for MOC3, dump_model.c-diffable) file contents.
*/
/**
* Runs `dump <file> [--sections] [--xml] [--puppet]`.
*
* @param List arguments The subcommand's arguments.
* @return Int The exit code.
*/
internal fun runDump(arguments: List<String>): Int {
val flags = arguments.filter { argument -> argument.startsWith("--") }.toSet()
val positionals = arguments.filterNot { argument -> argument.startsWith("--") }
val unknownFlags = flags - setOf("--sections", "--xml", "--puppet")
if (unknownFlags.isNotEmpty()) {
throw CliUsageException("unknown dump flag(s): ${unknownFlags.joinToString(", ")}")
}
if (positionals.size != 1) {
throw CliUsageException("usage: dump <file> [--sections] [--xml] [--puppet]")
}
val loaded = loadInput(positionals[0])
when (loaded) {
is LoadedInput.Moc3Input -> {
if ("--xml" in flags) {
throw CliUsageException("--xml applies to cmo3 input only")
}
if ("--sections" in flags) {
dumpMoc3Sections(loaded)
} else {
dumpMoc3Document(loaded.document)
}
}
is LoadedInput.Cmo3Input -> {
if ("--sections" in flags) {
throw CliUsageException("--sections applies to moc3 input only")
}
if ("--xml" in flags) {
dumpCmo3Xml(loaded.model)
return 0
}
dumpCmo3Overview(loaded.model)
}
is LoadedInput.SourceArtInput -> {
if ("--sections" in flags || "--xml" in flags) {
throw CliUsageException("--sections and --xml do not apply to source artwork")
}
dumpSourceArt(loaded)
}
}
if ("--puppet" in flags) {
dumpPuppetSummary(importPuppet(loaded))
}
return 0
}
/**
* The MOC3 semantic summary, mirroring dump_model.c's static line grammar (`P`/`T`/`D` records) so
* the relive harness's diff scripts can consume it. Runtime-evaluated columns (posed draw/render
* order, evaluated opacities, vertex-position hashes) are deliberately absent - this dumps the
* static rig, not a revived core.
*
* @param MocDocument document The decoded moc.
*/
private fun dumpMoc3Document(document: MocDocument) {
println("# MOC3 version=${document.version.byteValue}")
document.canvas?.let { canvas ->
val size = "${formatSixSignificant(canvas.width)},${formatSixSignificant(canvas.height)}"
val origin = "${formatSixSignificant(canvas.originX)},${formatSixSignificant(canvas.originY)}"
println("# canvas size=$size origin=$origin ppu=${formatSixSignificant(canvas.pixelsPerUnit)}")
}
println(
"# counts parameters=${document.parameters.size} parts=${document.parts.size} " +
"drawables=${document.artMeshes.size} deformers=${document.deformers.size} " +
"glues=${document.glues.size} groups=${document.renderOrderGroups.size} " +
"bindings=${document.bindings.size} blendShapes=${document.blendShapes.size} " +
"offscreens=${document.offscreens.size}",
)
println("[parameters]")
document.parameters.forEachIndexed { parameterIndex, parameter ->
println(
"P $parameterIndex id=${parameter.id} type=${parameter.type?.number ?: -1} " +
"min=${formatSixSignificant(parameter.minimumValue)} max=${formatSixSignificant(parameter.maximumValue)} " +
"def=${formatSixSignificant(parameter.defaultValue)} repeat=${if (parameter.repeats) 1 else 0}",
)
}
println("[parts]")
document.parts.forEachIndexed { partIndex, part ->
println("T $partIndex id=${part.id} parent=${part.parentPartIndex}")
}
println("[drawables]")
document.artMeshes.forEachIndexed { meshIndex, artMesh ->
println(
"D $meshIndex id=${artMesh.id} cflag=0x${(artMesh.constantFlags and 0xFF).toString(16).padStart(2, '0')} " +
"tex=${artMesh.textureIndex} part=${artMesh.parentPartIndex} vtx=${artMesh.vertexCount} " +
"idx=${artMesh.triangleIndices.size} masks=${artMesh.maskDrawableIndices.size}",
)
}
}
/**
* The MOC3 container tier: version, CountInfo, and per-section presence with element counts.
*
* @param LoadedInput.Moc3Input loaded The moc3 input (re-read at the container tier).
*/
private fun dumpMoc3Sections(loaded: LoadedInput.Moc3Input) {
val container = MocCodec.read(loaded.family.mocFile.readBytes())
println("# MOC3 version=${container.versionByte} sections=${container.sectionCount} bigEndian=${container.isBigEndian}")
println("# countInfo ${container.countInfo.joinToString(",")}")
var presentCount = 0
for (section in Section.entries) {
if (!container.sections.isPresent(section)) {
continue
}
presentCount++
println("S ${section.name} count=${container.sections.elementCount(section)}")
}
println("# sections present=$presentCount modeled=${Section.entries.size}")
}
/**
* The CMO3 overview: target version, the CAFF entry table, the embedded image resources, and the
* parsed main.xml prologue summary.
*
* @param Cmo3Model model The read model.
*/
private fun dumpCmo3Overview(model: Cmo3Model) {
val archive = model.archive
println("# CMO3 targetVersionNo=${model.targetVersionNo ?: "-"}")
println(
"# caff formatVersion=${archive.formatVersion.joinToString(".")} " +
"archiveVersion=${archive.archiveVersion.joinToString(".")} " +
"obfuscateKey=${archive.obfuscateKey}",
)
println("[entries]")
archive.entries.forEachIndexed { entryIndex, entry ->
println(
"E $entryIndex path=${entry.path} tag=${entry.tag} size=${entry.content.size} " +
"compression=${entry.compression} obfuscated=${if (entry.obfuscated) 1 else 0}",
)
}
println("[images]")
model.imageResources().forEachIndexed { imageIndex, resource ->
val pngSize = model.extractLayerPng(resource)?.size ?: 0
println("I $imageIndex type=${resource.type} width=${resource.width} height=${resource.height} pngBytes=$pngSize")
}
val mainXml = archive.firstByTag(CaffArchive.TAG_MAIN_XML)
if (mainXml != null) {
// sharedElements/mainElements are JDOM-typed and JDOM stays :format-internal; the class-version
// table and import list are the useful prologue summary anyway.
val parsed = ModelDocument.parse(mainXml.content)
println("[xml]")
println("# versions ${parsed.versions.entries.joinToString(" ") { (className, versionNumber) -> "$className=$versionNumber" }}")
println("# imports ${parsed.imports.joinToString(" ")}")
}
}
/**
* Writes the decompressed main.xml to stdout byte-for-byte, so a shell redirect round-trips it.
* CaffEntry.content is already inflated and deobfuscated by the CAFF read.
*
* @param Cmo3Model model The read model.
*/
private fun dumpCmo3Xml(model: Cmo3Model) {
val mainXml =
model.archive.firstByTag(CaffArchive.TAG_MAIN_XML)
?: throw IllegalStateException("archive has no main_xml entry")
System.out.write(mainXml.content)
System.out.flush()
}
/**
* The imported-puppet summary: entity counts and the parameter table - the exact import path the
* convert command lowers from, so a suspect conversion can be inspected at this tier first.
*
* @param PuppetModel puppet The imported puppet.
*/
private fun dumpPuppetSummary(puppet: PuppetModel) {
println("[puppet]")
println(
"# counts parameters=${puppet.parameters.size} parts=${puppet.parts.size} " +
"deformers=${puppet.deformers.size} drawables=${puppet.drawables.size} glues=${puppet.glues.size}",
)
println(
"# canvas ${formatSixSignificant(puppet.canvasWidth)}x${formatSixSignificant(puppet.canvasHeight)} " +
"origin=${formatSixSignificant(puppet.worldOriginX)},${formatSixSignificant(puppet.worldOriginZ)} " +
"target=${puppet.runtimeTarget.name}",
)
puppet.parameters.forEachIndexed { parameterIndex, parameter ->
println(
"P $parameterIndex id=${parameter.id.raw} min=${formatSixSignificant(parameter.min)} " +
"max=${formatSixSignificant(parameter.max)} def=${formatSixSignificant(parameter.default)}",
)
}
}
/**
* The source-artwork summary: canvas, folder attributes, and one line per layer.
*
* The layer inventory a PSD/CLIP/KRA reader produces has had no way to be seen until now, which is
* the same gap the atlas command closes on the packing side - this is what you read to judge whether
* a pack skipped the layers it should have. The alpha column is the packer's own view: the trimmed
* opaque bounds, or `empty` for a layer with no opaque pixel (which never reaches a page).
*
* @param LoadedInput.SourceArtInput loaded The loaded artwork document.
*/
private fun dumpSourceArt(loaded: LoadedInput.SourceArtInput) {
val art = loaded.art
val rasterLayerCount = art.layers.count { layer -> layer.kind == SourceLayerKind.Raster }
println("[artwork] ${loaded.file.name}")
println("# canvas ${art.widthPx}x${art.heightPx}")
println("# counts layers=${art.layers.size} raster=$rasterLayerCount groups=${art.groups.size}")
art.groups.forEach { group ->
println(
"G path=${group.path} name=${group.name} vis=${if (group.visible) 1 else 0} " +
"op=${formatSixSignificant(group.opacity)} blend=${group.blend} " +
"clip=${if (group.clipped) 1 else 0} through=${if (group.passThrough) 1 else 0}",
)
}
art.layers.forEachIndexed { layerIndex, layer ->
val trimmed = layer.analyzeAlpha(contourEpsilon = 0f)
val alphaColumn =
if (trimmed == null) {
"empty"
} else {
"${trimmed.opaqueBounds.width}x${trimmed.opaqueBounds.height}" +
"+${trimmed.opaqueBounds.left}+${trimmed.opaqueBounds.top}"
}
println(
"L $layerIndex order=${layer.order} kind=${layer.kind} id=${layer.id.raw} name=${layer.name} " +
"at=${layer.bounds.left},${layer.bounds.top} size=${layer.bounds.width}x${layer.bounds.height} " +
"alpha=$alphaColumn op=${formatSixSignificant(layer.opacity)} blend=${layer.blend} " +
"vis=${if (layer.visible) 1 else 0} clip=${if (layer.clipped) 1 else 0} group=${layer.groupPath}",
)
}
}
@@ -0,0 +1,69 @@
package org.umamo.cli
import java.io.File
import java.util.Locale
/*
* The extract subcommand: unpack a cmo3's CAFF archive into loose files - the plaintext main.xml
* plus every embedded layer PNG.
*/
/**
* Runs `extract <file> [<directory>]`.
*
* The entries land in a NEW subdirectory named after the model, created under the given directory
* (default: the input file's own directory) - `extract Model.cmo3 test/work/` writes into
* `test/work/Model/`. The subdirectory is deliberate accident insurance: extraction never mixes
* its output into a folder that already holds other files.
*
* @param List arguments The subcommand's arguments.
* @return Int The exit code.
*/
internal fun runExtract(arguments: List<String>): Int {
val positionals = arguments.filterNot { argument -> argument.startsWith("--") }
if (arguments.size != positionals.size || positionals.isEmpty() || positionals.size > 2) {
throw CliUsageException("Usage: extract <file> [<directory>]")
}
val loaded = loadInput(positionals[0])
if (loaded !is LoadedInput.Cmo3Input) {
throw CliUsageException("Extract applies to cmo3 input only")
}
val inputFile = File(positionals[0])
val modelName =
inputFile.name.let { fileName ->
if (fileName.lowercase(Locale.ROOT).endsWith(".cmo3")) fileName.dropLast(".cmo3".length) else fileName
}
val parentDirectory = if (positionals.size == 2) File(positionals[1]) else (inputFile.parentFile ?: File("."))
val extractionDirectory = File(parentDirectory, modelName)
if (extractionDirectory.exists()) {
System.err.println("Note: ${extractionDirectory.path} already exists; its matching files will be overwritten.")
}
extractionDirectory.mkdirs()
val archive = loaded.model.archive
val writtenNames = HashSet<String>()
archive.entries.forEachIndexed { entryIndex, entry ->
// Entry paths are archive data: guard against traversal and collisions rather than trusting them.
val safeName = entry.path.ifBlank { "entry_$entryIndex" }
val uniqueName = if (writtenNames.add(safeName)) safeName else "entry_${entryIndex}_$safeName"
val target = File(extractionDirectory, uniqueName)
if (!target.canonicalFile.toPath().startsWith(extractionDirectory.canonicalFile.toPath())) {
throw IllegalStateException("Archive entry escapes the extraction directory: ${entry.path}")
}
target.parentFile?.mkdirs()
// CaffEntry.content is already inflated and deobfuscated, so main.xml lands as plaintext.
target.writeBytes(entry.content)
println("Extracted ${target.path} (${entry.content.size} bytes)")
}
if (archive.preview.present) {
val previewTarget = File(extractionDirectory, "preview.png")
if (writtenNames.contains("preview.png")) {
System.err.println("Note: An archive entry already claimed preview.png; the CAFF preview image was skipped.")
} else {
previewTarget.writeBytes(archive.preview.png!!)
println("Extracted ${previewTarget.path} (${archive.preview.png!!.size} bytes, CAFF preview)")
}
}
println("Extracted ${archive.entries.size} entries into ${extractionDirectory.path}")
return 0
}
@@ -0,0 +1,113 @@
package org.umamo.cli
import kotlin.system.exitProcess
/*
* The Umamo diagnostic CLI: dump / extract / atlas / convert / diff over cmo3, moc3, and source
* artwork files.
*
* Replaces the diagnostic-tests-in-disguise workflow (Cmo3ResaveDumpTest's -Dcmo3.resave, ad-hoc
* probe printlns) with a proper operator tool. Data goes to stdout, diagnostics to stderr; exit 0
* on success, 1 on a command failure, 2 on a usage error.
*/
private const val USAGE = """Umamo diagnostic CLI
Usage (via Gradle; -q suppresses Gradle's own build output, leaving only this tool's):
./gradlew -q :cli:run --args="dump <file> [--sections] [--xml] [--puppet]"
./gradlew -q :cli:run --args="extract <file> [<directory>]"
./gradlew -q :cli:run --args="atlas <file> [<directory>] [options]"
./gradlew -q :cli:run --args="convert <in> <out>"
./gradlew -q :cli:run --args="diff <a> <b>"
Commands:
dump <file> Print a cmo3/moc3/artwork file's contents. MOC3 defaults to printing
a static rig summary. CMO3 defaults to the archive entry table plus
the parsed main.xml overview. Source artwork(PSD, CLIP, KRA, or a
flat raster) prints its canvas, folders, and per-layer inventory with
each layer's trimmed opaque bounds.
--sections MOC3 container tier: per-section presence and counts.
--xml CMO3 only: the decompressed main.xml, byte-for-byte.
--puppet Either format: import to a PuppetModel and summarize.
extract <file> [<directory>]
Unpack a cmo3's archive into loose files: The plaintext main.xml plus
every embedded layer PNG. Files write to a NEW subdirectory named
after the model, created under <directory> (Default: The file's own
directory) - `extract Model.cmo3 test/work/` writes test/work/Model/.
atlas <file> [<directory>]
Pack a source artwork document(PSD, CLIP, KRA, or a flat raster) into
texture atlas pages. Writes page_NN.png plus placements.txt to a NEW
subdirectory named after the input, then reads every packed tile back
out of its page and fails if any byte differs. Layers with no opaque
pixels, or too large for a page, are reported rather than dropped.
--page-size=N Page side to pack against (Default: 4096).
--gutter=N Transparent spacing around every tile (Default: 2).
--extrude=N Edge pixels replicated into the gutter (Default: 2).
--rotate Allow quarter-turning tiles to pack tighter.
--visible-only Skip layers hidden by their own or a folder's eye.
--no-shrink Keep full --page-size pages instead of cropping.
--preview Also write preview.png: the canvas recomposited
from the packed pages (Source-over; blend modes
and layer opacity ignored).
convert <in> <out>
Direction by input format and output extension:
cmo3 -> cmo3 Resave (An unedited main.xml will reemit byte-identical.)
moc3 -> moc3 Rebake (Fresh synthesis, NOT byte-identical by design.)
cmo3 -> moc3 Full family: moc3 + model3.json + cdi3.json + textures
moc3 -> cmo3 Fresh-graph synthesis (Cubism can open it; the source
art pages are atlas copies, so a MissingSourceArt
notice is always reported.)
A moc3 input may also be given as its .model3.json manifest; sibling
sidecars (model3/cdi3/physics3/pose3/userdata3) are discovered by
the manifest's own file references.
diff <a> <b> Import both files (either format) and print the semantic per-entity
difference.
help This text."""
/**
* The CLI entry point: dispatches to a subcommand and converts its outcome to an exit code.
*
* @param Array args The raw command-line arguments (Gradle's --args, split).
*/
fun main(args: Array<String>) {
val exitCode = runCli(args.toList())
if (exitCode != 0) {
exitProcess(exitCode)
}
}
/**
* Runs one CLI invocation. Split from main so the dispatch stays testable without exiting the JVM.
*
* @param List arguments The command line: a verb followed by its positionals and flags.
* @return Int The process exit code (0 success, 1 failure, 2 usage error).
*/
internal fun runCli(arguments: List<String>): Int {
if (arguments.isEmpty() || arguments[0] == "help" || arguments[0] == "--help") {
println(USAGE)
return if (arguments.isEmpty()) 2 else 0
}
return try {
when (arguments[0]) {
"dump" -> runDump(arguments.drop(1))
"extract" -> runExtract(arguments.drop(1))
"atlas" -> runAtlas(arguments.drop(1))
"convert" -> runConvert(arguments.drop(1))
"diff" -> runDiff(arguments.drop(1))
else -> {
System.err.println("unknown command '${arguments[0]}'")
System.err.println(USAGE)
2
}
}
} catch (usageError: CliUsageException) {
System.err.println(usageError.message)
2
} catch (failure: Exception) {
System.err.println("error: ${failure.message ?: failure::class.simpleName}")
1
}
}
/** A malformed invocation - reported as usage (exit 2) rather than a command failure (exit 1). */
internal class CliUsageException(message: String) : Exception(message)