Add record CLI command for headless GIF/PNG capture

dwursteisen · claude · dwursteisen · commit 5888220822e0 · 2026-02-26T21:24:31.000+01:00
- Add `tiny-cli record` command that runs a game headless and captures
  frames as GIF or PNG
- Support --duration, --frames, --output, and --include-boot options
- Add headless and maxFrames fields to GameOptions
- Implement endGameLoop() in GlfwPlatform to signal window close
- Add clearRecordingCache() to Platform for boot frame exclusion
- Add synchronous recordSync/screenshotSync methods to GlfwPlatform
- Auto-stop game loop in GameEngine when maxFrames is reached

Co-Authored-By: Claude Opus 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/tiny-cli/src/main/kotlin/com/github/minigdx/tiny/cli/command/DocsCommand.kt b/tiny-cli/src/main/kotlin/com/github/minigdx/tiny/cli/command/DocsCommand.kt
@@ -52,6 +52,7 @@ class DocsCommand : CliktCommand(name = "docs") {
                 SfxCommand(),
                 UpdateCommand(),
                 ResourcesCommand(),
+                RecordCommand(),
             )
 
             // Generate documentation for each command
diff --git a/tiny-cli/src/main/kotlin/com/github/minigdx/tiny/cli/command/MainCommand.kt b/tiny-cli/src/main/kotlin/com/github/minigdx/tiny/cli/command/MainCommand.kt
@@ -16,6 +16,7 @@ class MainCommand : CliktCommand() {
             PaletteCommand(),
             SfxCommand(),
             UpdateCommand(),
+            RecordCommand(),
             ResourcesCommand(),
             DocsCommand(),
         )
diff --git a/tiny-cli/src/main/kotlin/com/github/minigdx/tiny/cli/command/RecordCommand.kt b/tiny-cli/src/main/kotlin/com/github/minigdx/tiny/cli/command/RecordCommand.kt
@@ -0,0 +1,113 @@
+package com.github.minigdx.tiny.cli.command
+
+import com.github.ajalt.clikt.core.Abort
+import com.github.ajalt.clikt.core.CliktCommand
+import com.github.ajalt.clikt.core.Context
+import com.github.ajalt.clikt.parameters.arguments.argument
+import com.github.ajalt.clikt.parameters.arguments.default
+import com.github.ajalt.clikt.parameters.options.default
+import com.github.ajalt.clikt.parameters.options.flag
+import com.github.ajalt.clikt.parameters.options.option
+import com.github.ajalt.clikt.parameters.types.file
+import com.github.ajalt.clikt.parameters.types.int
+import com.github.ajalt.clikt.parameters.types.long
+import com.github.minigdx.tiny.cli.config.GameParameters
+import com.github.minigdx.tiny.engine.GameEngine
+import com.github.minigdx.tiny.engine.GameEngineListener
+import com.github.minigdx.tiny.file.CommonVirtualFileSystem
+import com.github.minigdx.tiny.log.LogLevel
+import com.github.minigdx.tiny.log.StdOutLogger
+import com.github.minigdx.tiny.platform.glfw.GlfwPlatform
+import com.github.minigdx.tiny.resources.GameScript
+import java.io.File
+
+class RecordCommand : CliktCommand(name = "record") {
+    val gameDirectory by argument(help = "The directory containing your game to record.")
+        .file(mustExist = true, canBeDir = true, canBeFile = false)
+        .default(File("."))
+
+    val duration by option("--duration", "-d", help = "Duration in seconds (default: 5)")
+        .int()
+        .default(5)
+
+    val frames by option("--frames", "-f", help = "Number of frames to capture (overrides --duration)")
+        .long()
+
+    val output by option("--output", "-o", help = "Output file path (extension determines format: .png for screenshot, .gif for animation)")
+
+    val headless by option("--headless", help = "Run without displaying the game window")
+        .flag()
+
+    val includeBoot by option("--include-boot", help = "Include the boot animation in the recording")
+        .flag()
+
+    override fun help(context: Context) = "Record your game as a GIF or PNG screenshot."
+
+    override fun run() {
+        val configFile = gameDirectory.resolve("_tiny.json")
+        if (!configFile.exists()) {
+            echo("No _tiny.json found in ${gameDirectory.absolutePath}! Can't record the game without it.")
+            throw Abort()
+        }
+
+        val gameParameters = GameParameters.read(configFile)
+        val maxFrames = frames ?: (duration * 60L)
+        val outputFile = File(output ?: gameDirectory.resolve("recording.gif").path)
+        val isScreenshot = outputFile.extension.lowercase() == "png"
+
+        val logger = StdOutLogger("tiny-cli", level = LogLevel.INFO)
+        val homeDirectory = findHomeDirectory(gameParameters)
+        val vfs = CommonVirtualFileSystem()
+
+        val baseOptions = gameParameters.toGameOptions()
+        val recordSeconds = (maxFrames / 60f) + 1f
+        val gameOption = baseOptions.copy(
+            headless = headless,
+            maxFrames = maxFrames,
+            record = recordSeconds,
+        )
+
+        val platform = GlfwPlatform(
+            gameOption,
+            logger,
+            vfs,
+            gameDirectory,
+            homeDirectory,
+        )
+
+        val gameEngine = GameEngine(
+            gameOptions = gameOption,
+            platform = platform,
+            vfs = vfs,
+            logger = logger,
+            listener = object : GameEngineListener {
+                override fun switchScript(
+                    before: GameScript?,
+                    after: GameScript?,
+                ) {
+                    if (!includeBoot) {
+                        platform.clearRecordingCache()
+                    }
+                }
+
+                override fun reload(gameScript: GameScript?) = Unit
+            },
+        )
+
+        echo("Recording ${if (isScreenshot) "screenshot" else "GIF"} ($maxFrames frames)...")
+
+        gameEngine.main()
+
+        if (isScreenshot) {
+            platform.screenshotSync(outputFile)
+        } else {
+            platform.recordSync(outputFile)
+        }
+
+        echo("Saved to ${outputFile.absolutePath}")
+
+        // Force exit as the sound manager may keep background threads alive.
+        @Suppress("ExitProcess")
+        kotlin.system.exitProcess(0)
+    }
+}
diff --git a/tiny-engine/src/commonMain/kotlin/com/github/minigdx/tiny/engine/GameEngine.kt b/tiny-engine/src/commonMain/kotlin/com/github/minigdx/tiny/engine/GameEngine.kt
@@ -115,6 +115,10 @@ class GameEngine(
             accumulator -= REFRESH_LIMIT
             currentFrame++
 
+            if (gameOptions.maxFrames > 0 && currentFrame >= gameOptions.maxFrames) {
+                platform.endGameLoop()
+            }
+
             interceptUserShortcup()
             currentMetrics?.run { storeFrameMetrics(this) }
 
diff --git a/tiny-engine/src/commonMain/kotlin/com/github/minigdx/tiny/engine/GameOptions.kt b/tiny-engine/src/commonMain/kotlin/com/github/minigdx/tiny/engine/GameOptions.kt
@@ -22,6 +22,9 @@ data class GameOptions(
     val bootScript: String? = null,
     val icon: String? = null,
     val fonts: List<FontDescriptor> = emptyList(),
+    val headless: Boolean = false,
+    // 0 = unlimited
+    val maxFrames: Long = 0L,
 ) : MouseProject {
     init {
         require(width > 0) { "The width needs to be a positive number." }
diff --git a/tiny-engine/src/commonMain/kotlin/com/github/minigdx/tiny/platform/Platform.kt b/tiny-engine/src/commonMain/kotlin/com/github/minigdx/tiny/platform/Platform.kt
@@ -47,6 +47,11 @@ interface Platform {
      */
     fun screenshot() = Unit
 
+    /**
+     * Clear the recording frame cache.
+     */
+    fun clearRecordingCache() = Unit
+
     /**
      * Write an image from a frame using index as colors
      */
diff --git a/tiny-engine/src/jvmMain/kotlin/com/github/minigdx/tiny/platform/glfw/GlfwPlatform.kt b/tiny-engine/src/jvmMain/kotlin/com/github/minigdx/tiny/platform/glfw/GlfwPlatform.kt
@@ -160,7 +160,9 @@ class GlfwPlatform(
         GLFW.glfwSwapInterval(1)
 
         // Make the window visible
-        GLFW.glfwShowWindow(window)
+        if (!gameOptions.headless) {
+            GLFW.glfwShowWindow(window)
+        }
 
         // Get the size of the device window
         val tmpWidth = MemoryUtil.memAllocInt(1)
@@ -218,7 +220,13 @@ class GlfwPlatform(
         GLFW.glfwTerminate()
     }
 
-    override fun endGameLoop() = Unit
+    override fun endGameLoop() {
+        GLFW.glfwSetWindowShouldClose(window, true)
+    }
+
+    override fun clearRecordingCache() {
+        gifFrameCache.clear()
+    }
 
     override fun newFrameRendered(virtualFrameBuffer: VirtualFrameBuffer) {
         virtualFrameBuffer.readFrameBuffer().copyInto(lastDraw)
@@ -283,6 +291,56 @@ class GlfwPlatform(
         }
     }
 
+    fun recordSync(outputFile: File) {
+        logger.info("GLFW") { "Starting to generate GIF in '${outputFile.absolutePath}' (Wait for it...)" }
+        val buffer = mutableListOf<ByteArray>().apply {
+            addAll(gifFrameCache)
+        }
+
+        val now = System.currentTimeMillis()
+        val options = ImageOptions().apply {
+            this.setDelay(20, TimeUnit.MILLISECONDS)
+        }
+        outputFile.outputStream().buffered().use { out ->
+            val encoder = FastGifEncoder(
+                out,
+                gameOptions.width,
+                gameOptions.height,
+                0,
+                gameOptions.colors(),
+            )
+
+            buffer.forEach { frame ->
+                encoder.addIndexedImage(frame, gameOptions.width, options)
+            }
+            encoder.finishEncoding()
+        }
+        logger.info("GLFW") { "Screen recorded in '${outputFile.absolutePath}' in ${System.currentTimeMillis() - now} ms" }
+    }
+
+    fun screenshotSync(outputFile: File) {
+        val buffer = lastDraw.pixels.copyOf()
+        val width = gameOptions.width
+        val height = gameOptions.height
+        val image = BufferedImage(width, height, BufferedImage.TYPE_INT_ARGB)
+
+        for (y in 0 until height) {
+            for (x in 0 until width) {
+                val colorData = gameOptions.colors().getRGBA(buffer[x + y * width].toInt())
+
+                val r = colorData[0].toInt() and 0xff
+                val g = colorData[1].toInt() and 0xff
+                val b = colorData[2].toInt() and 0xff
+                val a = colorData[3].toInt() and 0xff
+                val color = (a shl 24) or (r shl 16) or (g shl 8) or b
+                image.setRGB(x, y, color)
+            }
+        }
+
+        ImageIO.write(image, "png", outputFile)
+        logger.info("GLFW") { "Screenshot saved in '${outputFile.absolutePath}'" }
+    }
+
     override fun writeImage(buffer: ByteArray) {
         val origin = newFile("screenshoot", "png")
         val width = gameOptions.width

Original file line number	Diff line number	Diff line change
`@@ -52,6 +52,7 @@ class DocsCommand : CliktCommand(name = "docs") {`
`52`	`52`	`SfxCommand(),`
`53`	`53`	`UpdateCommand(),`
`54`	`54`	`ResourcesCommand(),`
	`55`	`+ RecordCommand(),`
`55`	`56`	`)`
`56`	`57`
`57`	`58`	`// Generate documentation for each command`
Original file line number	Diff line number	Diff line change
`@@ -16,6 +16,7 @@ class MainCommand : CliktCommand() {`
`16`	`16`	`PaletteCommand(),`
`17`	`17`	`SfxCommand(),`
`18`	`18`	`UpdateCommand(),`
	`19`	`+ RecordCommand(),`
`19`	`20`	`ResourcesCommand(),`
`20`	`21`	`DocsCommand(),`
`21`	`22`	`)`