Merge pull request #23 from minigdx/full-shaders

Full shaders

Author: dwursteisen

.gitignore

@@ -4,6 +4,9 @@ build/
 !**/src/main/**/build/
 !**/src/test/**/build/
 
+# Test screenshots (generated during test runs)
+.test/
+
 ### IntelliJ IDEA ###
 .idea/**
 .idea/

.idea/gradle.xml

@@ -28,7 +28,17 @@ Tiny is a Kotlin Multiplatform game engine with Lua scripting support that compi
 ```bash
 ./gradlew build                    # Build all modules
 ./gradlew test                     # Run all tests
-./gradlew publishToMavenLocal      # Deploy to local maven
+./gradlew publishToMavenLocal      # Deploy to local maven (also: make deploy)
+./gradlew clean                    # Clean build artifacts
+```
+
+### Testing
+```bash
+./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
@@ -37,22 +47,36 @@ make lint          # or ./gradlew ktlintCheck
 make lintfix       # or ./gradlew ktlintFormat
 ```
 
-### CLI Installation
+### CLI Development
 ```bash
 make install       # Build and install CLI to ~/.bin/tiny-cli
+./gradlew :tiny-cli:assembleDist   # Build CLI distribution
+```
+
+### Documentation Generation
+```bash
+make docs          # Generate full documentation (requires CLI install)
+./gradlew asciidoctor              # Generate docs only
 ```
 
-### Documentation
+### CLI Commands (after installation)
 ```bash
-make docs          # Generate documentation (requires CLI install)
+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)
-- `WebGlPlatform` for web (WebGL)
+- `GlfwPlatform` for desktop (LWJGL/GLFW). It uses OpenGL 3.
+- `WebGlPlatform` for web (WebGL). It uses WebGL 2.0.
 
 ### Resource Management
 Games are structured around:
@@ -69,22 +93,61 @@ The engine exposes functionality through organized Lua libraries:
 - `ctrl`: Input handling
 - `map`: Level/tilemap operations
 
-### Build Artifacts
+### 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
+- `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
 
-1. Engine changes go in `tiny-engine/src/commonMain/kotlin`
-2. CLI commands are in `tiny-cli/src/main/kotlin/com/github/minigdx/tiny/cli/command/`
-3. Lua API libraries are in `tiny-engine/src/commonMain/kotlin/com/github/minigdx/tiny/lua/`
-4. Tests follow the pattern `src/commonTest/kotlin` for shared tests
-5. Platform-specific code uses `src/jvmMain` and `src/jsMain` directories
+### 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
 
-The project uses hot-reload for rapid development - games can be updated without restarting the engine.
+### 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
@@ -95,6 +158,7 @@ You are Coding Copilot, configured to assist in a multi-language codebase (Kotli
 - 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.

.idea/misc.xml

@@ -34,6 +34,19 @@ end
 
 ---
 
+## ⌨️ CLI Commands
+
+```bash
+tiny-cli create <name>    # Create new game
+tiny-cli run              # Run game
+tiny-cli debug            # Run with debugger
+tiny-cli serve            # Dev server with hot reload
+tiny-cli export           # Export for web
+tiny-cli palette          # Generate color palettes
+tiny-cli sfx              # Sound effect editor
+tiny-cli add              # Add resources to project
+```
+
 ## 📦 Download
 
 Get the latest version from the [Releases Page](https://github.com/minigdx/tiny/releases).
@@ -72,6 +85,18 @@ Want to create games like these? Dive into the docs and start building:
 
 ---
 
+## 🤝 Contributing
+
+We welcome contributions!
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+---
+
 ## 📄 License
 
 🧸 Tiny is open-source software licensed under the [MIT License](https://github.com/minigdx/tiny/blob/main/LICENSE).

CLAUDE.md

@@ -3,11 +3,10 @@ org.gradle.caching=true
 org.gradle.configureondemand=true
 org.gradle.jvmargs=-Xmx2048M
 org.gradle.parallel=true
-# Configuration cache doesn't play well with application plugin and jvmArgs.
-# org.gradle.unsafe.configuration-cache=true
+org.gradle.unsafe.configuration-cache=false
 
 # Test K2 (not working yet)
 # minigdx.mpp.k2=true
 
 org.jetbrains.dokka.experimental.gradle.pluginMode=V2Enabled
-org.jetbrains.dokka.experimental.gradle.pluginMode.noWarn=true
+org.jetbrains.dokka.experimental.gradle.pluginMode.noWarn=true

README.md

@@ -1,18 +1,18 @@
 [versions]
-asciidoctorj = "3.3.2"
+asciidoctorj = "4.0.4"
 clikt = "5.0.3"
 gifencoder = "0.10.1"
 jna = "5.14.0"
-kgl = "0.8.4"
+kgl = "0.9.0"
 kotlin-coroutines = "1.10.2"
-kotlin-ksp = "2.1.20-1.0.32"
-kotlin-serialization = "2.1.20"
-kotlin-serialization-json = "1.8.1"
-ktor = "3.1.2"
-luak = "1.1.0"
+kotlin-ksp = "2.2.20-2.0.4"
+kotlin-serialization = "2.2.20"
+kotlin-serialization-json = "1.9.0"
+ktor = "3.3.1"
+luak = "1.2.0"
 lwjgl = "3.3.6"
-minigdx-developer = "1.4.2"
-mokkery = "2.7.2"
+minigdx-developer = "1.5.0"
+mokkery = "2.10.1"
 rsyntax = "3.6.0"
 slf4j = "2.0.7"
 
@@ -23,6 +23,7 @@ jna = {module="net.java.dev.jna:jna-platform", version.ref = "jna"}
 rsyntax = {module="com.fifesoft:rsyntaxtextarea", version.ref = "rsyntax"}
 
 kotlin-coroutines = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-core", version.ref = "kotlin-coroutines" }
+kotlin-coroutines-test = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-test", version.ref = "kotlin-coroutines" }
 kotlin-serialization-json = { module = "org.jetbrains.kotlinx:kotlinx-serialization-json", version.ref = "kotlin-serialization-json" }
 
 luak = { module = "com.github.minigdx:luak", version.ref = "luak" }