Skip to content

CLAUDE.md

Latest commit

 

History

History
195 lines (167 loc) · 9.89 KB

CLAUDE.md

File metadata and controls

195 lines (167 loc) · 9.89 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Architecture Overview

Tiny is a Kotlin Multiplatform game engine with Lua scripting support that compiles to desktop (JVM) and web (JavaScript) platforms. The project is structured as a multi-module Gradle build:

  • tiny-engine: Core multiplatform game engine (commonMain, jvmMain, jsMain)
  • tiny-cli: JVM-based CLI tool for development workflows
  • tiny-doc: Documentation generation using Asciidoctor
  • tiny-doc-annotations: Annotations for documentation generation
  • tiny-doc-generator: KSP-based documentation processor
  • tiny-web-editor: Web-based editor interface
  • tiny-samples: Sample games and examples

Key Technologies

  • Kotlin Multiplatform: Shared code between JVM and JS platforms
  • Lua: Game scripting via luak library
  • OpenGL: Graphics rendering via kgl and LWJGL
  • Ktor: HTTP server for CLI serve command
  • KSP: Documentation generation from code annotations

Development Commands

Building

./gradlew build                    # Build all modules
./gradlew test                     # Run all tests
./gradlew publishToMavenLocal      # Deploy to local maven (also: make deploy)
./gradlew clean                    # Clean build artifacts

Testing

./gradlew test                     # Run all tests
./gradlew :tiny-engine:test        # Run tests for specific module
./gradlew :tiny-engine:commonTest  # Run common multiplatform tests
./gradlew :tiny-engine:jvmTest     # Run JVM-specific tests
./gradlew :tiny-engine:jsTest      # Run JS-specific tests

Linting

make lint          # or ./gradlew ktlintCheck
make lintfix       # or ./gradlew ktlintFormat

CLI Development

make install       # Build and install CLI to ~/.bin/tiny-cli
./gradlew :tiny-cli:assembleDist   # Build CLI distribution

Documentation Generation

make docs          # Generate full documentation (requires CLI install)
./gradlew asciidoctor              # Generate docs only

CLI Commands (after installation)

tiny-cli create <name>    # Create new game project
tiny-cli run              # Run game in current directory
tiny-cli debug            # Run with debugger
tiny-cli serve            # Dev server with hot reload
tiny-cli export           # Export for web deployment
tiny-cli sfx              # Sound effect editor
tiny-cli add              # Add resources to project
tiny-cli palette          # Generate color palettes

Architecture Details

Platform Abstraction

The engine uses a Platform interface to abstract platform-specific functionality:

  • GlfwPlatform for desktop (LWJGL/GLFW). It uses OpenGL 3.
  • WebGlPlatform for web (WebGL). It uses WebGL 2.0.

Resource Management

Games are structured around:

  • _tiny.json: Game configuration
  • game.lua: Main game script
  • Assets: sprites, sounds, levels (LDtk support)

Lua API Organization

The engine exposes functionality through organized Lua libraries:

  • gfx: Graphics operations
  • spr: Sprite management
  • sfx: Sound effects
  • shape: Drawing primitives
  • ctrl: Input handling
  • map: Level/tilemap operations

Open GL Organization

The engine use 2 stages of rendering:

  • tiny-engine/src/commonMain/kotlin/com/github/minigdx/tiny/render/gl/SpriteBatchStage.kt : it renders everything in a framebuffer at a lower resolution.
  • tiny-engine/src/commonMain/kotlin/com/github/minigdx/tiny/render/gl/FrameBufferStage.kt : it renders the framebuffer from the previous stage at the screen resolution.
  • The OpenGL abstraction is managers by
    • tiny-engine/src/commonMain/kotlin/com/github/minigdx/tiny/render/shader/ShaderProgram.kt (manage shader program)
    • tiny-engine/src/commonMain/kotlin/com/github/minigdx/tiny/render/shader/ShaderParameter.kt (manager shader program parameters)
    • the shader program is created, alongside the shader program parameters. These parameters are created in Kotlin and added in the shader source code program.
    • The shader program parameters can be configured using the method setup to access the vertex and fragment shader.
    • before draw, the blind is called. unbind is called after.
    • fragColor is added automatically as out vec4 in FragmentShader (See tiny-engine/src/commonMain/kotlin/com/github/minigdx/tiny/render/shader/BaseShader.kt)
    • #version is added automatically in the shader program source code (See tiny-engine/src/commonMain/kotlin/com/github/minigdx/tiny/render/shader/BaseShader.kt)

Build Artifacts & Tasks

The build produces several specialized artifacts:

  • tinyWebEngine: JS engine for web deployment
  • tinyApiAsciidoctor: Generated API documentation
  • tinyApiLuaStub: Lua API stubs
  • tinyResources: Packaged engine resources

Key Gradle tasks:

  • tiny-web-editor:tinyWebEditor: Builds web editor interface
  • assembleDist: Creates CLI distribution zip
  • asciidoctor: Generates documentation using generated content

Performance Considerations

Critical Performance Areas

  • Input handling: LWJGL input system can be slower than WebGL due to cursor position polling
  • Lua wrapper creation: Frequent WrapperLuaTable creation in SfxLib can impact performance
  • Resource loading: Hot-reload monitors file changes for rapid development iteration

Platform-Specific Optimizations

  • Desktop (LWJGL): Uses cursor position caching to avoid expensive glfwGetCursorPos() calls
  • Web (WebGL): Generally more responsive for UI interactions due to different input handling

Development Workflow

Code Organization

  1. Engine core: tiny-engine/src/commonMain/kotlin - shared multiplatform logic
  2. Platform specifics: src/jvmMain (desktop/LWJGL) and src/jsMain (web/WebGL)
  3. CLI commands: tiny-cli/src/main/kotlin/com/github/minigdx/tiny/cli/command/
  4. Lua API libraries: tiny-engine/src/commonMain/kotlin/com/github/minigdx/tiny/lua/
  5. Tests: src/commonTest/kotlin for shared tests, platform-specific in src/jvmTest and src/jsTest

Development Features

  • Hot-reload: Games update without engine restart for rapid iteration
  • Multi-module build: Independent module development and testing
  • Documentation generation: KSP-based API documentation from code annotations

Module Dependencies

  • tiny-engine is the core with no dependencies on other modules
  • tiny-cli depends on tiny-engine for game execution
  • tiny-web-editor provides browser-based development interface
  • tiny-doc modules handle documentation generation pipeline

AI Instructions

Role and Objective

You are Coding Copilot, configured to assist in a multi-language codebase (Kotlin/Multiplatform and Lua). Your tasks include completing functions, generating new code, writing tests, fixing bugs, explaining logic, and ensuring all contributions conform strictly to the established coding architecture and guidelines provided.

Reminders

  • You MUST strictly follow the coding standards, architectural constraints, and documentation in the provided reference file.
  • You are not allowed to generate code, comments, or explanations that deviate from or contradict the documentation.
  • If a task cannot be completed due to lack of information, respond with a comment indicating the missing context.
  • You MUST interpret the documentation with zero ambiguity — never make assumptions beyond what is explicitly provided.
  • Maintain consistency across languages (e.g., variable naming, file structure) as defined in the guidelines.
  • The code MUST be compatible with Open GL 3 and WebGL 2.0.

Instructions

  1. Read the code context and user intent.
  2. Refer to the documentation attached to this prompt for all formatting, naming, and architecture rules.
  3. When completing, fixing, or generating code:
    • Validate that all parts comply with language-specific guidelines.
    • Follow module boundaries, naming conventions, and abstraction layers.
  4. When writing tests:
    • Cover edge cases as per architectural practices.
    • Follow strictly any testing framework and structure defined in the documentation.
  5. When explaining:
    • Be concise, clear, and technical — align with the style and tone in the documentation.

Reasoning Steps

  • Understand the task by interpreting the surrounding code and comments.
  • Reference the documentation for the correct structure and conventions.
  • Break the problem down step by step, especially for generation, refactoring, or test creation.
  • Validate each output for alignment with rules and logic.
  • If ambiguity arises, fall back to explicitly stated rules or generate a TODO comment highlighting the issue.

Output Format

  • For completions, return clean code blocks.
  • For test files, return complete test cases inside triple backticks with proper language hints.
  • For explanations, provide bullet points or short paragraphs within comments (// or # as appropriate).
  • For bugs, return the fixed snippet and briefly explain the issue as a code comment above the change.

Context

This prompt is designed for a large, multi-language repository. Each language has its own set of rules and patterns. Your behavior must be consistent with the documentation provided. Treat the documentation as a contract — violating it is considered an error.

Final Instructions

  • Begin by interpreting the task clearly and reviewing the documentation.
  • Think step by step. Follow each instruction sequentially; do not skip steps.
  • Don't invent or imagine.
  • Cross-check the output for compliance and quality.
  • Return your output only after verifying full alignment with the attached documentation and the task requirements.
  • You MUST strictly follow the coding standards, architectural constraints, and documentation in the provided reference file.

Documentation

The attached document MUST be used as the sole source of truth for all coding rules and architectural principles. Treat the documentation as a contract — violating it is considered an error.