@mclawnet/agent 0.6.20 → 0.6.22

package/skills/game-development/pc-games/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: pc-games
+description: "PC and console game development principles. Engine selection, platform features, optimization strategies."
+risk: safe
+source: community
+date_added: "2026-02-27"
+---
+
+# PC/Console Game Development
+
+> Engine selection and platform-specific principles.
+
+---
+
+## 1. Engine Selection
+
+### Decision Tree
+
+```
+What are you building?
+│
+├── 2D Game
+│   ├── Open source important? → Godot
+│   └── Large team/assets? → Unity
+│
+├── 3D Game
+│   ├── AAA visual quality? → Unreal
+│   ├── Cross-platform priority? → Unity
+│   └── Indie/open source? → Godot 4
+│
+└── Specific Needs
+    ├── DOTS performance? → Unity
+    ├── Nanite/Lumen? → Unreal
+    └── Lightweight? → Godot
+```
+
+### Comparison
+
+| Factor | Unity 6 | Godot 4 | Unreal 5 |
+|--------|---------|---------|----------|
+| 2D | Good | Excellent | Limited |
+| 3D | Good | Good | Excellent |
+| Learning | Medium | Easy | Hard |
+| Cost | Revenue share | Free | 5% after $1M |
+| Team | Any | Solo-Medium | Medium-Large |
+
+---
+
+## 2. Platform Features
+
+### Steam Integration
+
+| Feature | Purpose |
+|---------|---------|
+| Achievements | Player goals |
+| Cloud Saves | Cross-device progress |
+| Leaderboards | Competition |
+| Workshop | User mods |
+| Rich Presence | Show in-game status |
+
+### Console Requirements
+
+| Platform | Certification |
+|----------|--------------|
+| PlayStation | TRC compliance |
+| Xbox | XR compliance |
+| Nintendo | Lotcheck |
+
+---
+
+## 3. Controller Support
+
+### Input Abstraction
+
+```
+Map ACTIONS, not buttons:
+- "confirm" → A (Xbox), Cross (PS), B (Nintendo)
+- "cancel" → B (Xbox), Circle (PS), A (Nintendo)
+```
+
+### Haptic Feedback
+
+| Intensity | Use |
+|-----------|-----|
+| Light | UI feedback |
+| Medium | Impacts |
+| Heavy | Major events |
+
+---
+
+## 4. Performance Optimization
+
+### Profiling First
+
+| Engine | Tool |
+|--------|------|
+| Unity | Profiler Window |
+| Godot | Debugger → Profiler |
+| Unreal | Unreal Insights |
+
+### Common Bottlenecks
+
+| Bottleneck | Solution |
+|------------|----------|
+| Draw calls | Batching, atlases |
+| GC spikes | Object pooling |
+| Physics | Simpler colliders |
+| Shaders | LOD shaders |
+
+---
+
+## 5. Engine-Specific Principles
+
+### Unity 6
+
+- DOTS for performance-critical systems
+- Burst compiler for hot paths
+- Addressables for asset streaming
+
+### Godot 4
+
+- GDScript for rapid iteration
+- C# for complex logic
+- Signals for decoupling
+
+### Unreal 5
+
+- Blueprint for designers
+- C++ for performance
+- Nanite for high-poly environments
+- Lumen for dynamic lighting
+
+---
+
+## 6. Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|----------|-------|
+| Choose engine by hype | Choose by project needs |
+| Ignore platform guidelines | Study certification requirements |
+| Hardcode input buttons | Abstract to actions |
+| Skip profiling | Profile early and often |
+
+---
+
+> **Remember:** Engine is a tool. Master the principles, then adapt to any engine.
+
+## When to Use
+This skill is applicable to execute the workflow or actions described in the overview.
+
+## Limitations
+- Use this skill only when the task clearly matches the scope described above.
+- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
+- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.

package/skills/game-development/vr-ar/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: vr-ar
+description: "VR/AR development principles. Comfort, interaction, performance requirements."
+risk: unknown
+source: community
+date_added: "2026-02-27"
+---
+
+# VR/AR Development
+
+> Immersive experience principles.
+
+---
+
+## 1. Platform Selection
+
+### VR Platforms
+
+| Platform | Use Case |
+|----------|----------|
+| **Quest** | Standalone, wireless |
+| **PCVR** | High fidelity |
+| **PSVR** | Console market |
+| **WebXR** | Browser-based |
+
+### AR Platforms
+
+| Platform | Use Case |
+|----------|----------|
+| **ARKit** | iOS devices |
+| **ARCore** | Android devices |
+| **WebXR** | Browser AR |
+| **HoloLens** | Enterprise |
+
+---
+
+## 2. Comfort Principles
+
+### Motion Sickness Prevention
+
+| Cause | Solution |
+|-------|----------|
+| **Locomotion** | Teleport, snap turn |
+| **Low FPS** | Maintain 90 FPS |
+| **Camera shake** | Avoid or minimize |
+| **Rapid acceleration** | Gradual movement |
+
+### Comfort Settings
+
+- Vignette during movement
+- Snap vs smooth turning
+- Seated vs standing modes
+- Height calibration
+
+---
+
+## 3. Performance Requirements
+
+### Target Metrics
+
+| Platform | FPS | Resolution |
+|----------|-----|------------|
+| Quest 2 | 72-90 | 1832x1920 |
+| Quest 3 | 90-120 | 2064x2208 |
+| PCVR | 90 | 2160x2160+ |
+| PSVR2 | 90-120 | 2000x2040 |
+
+### Frame Budget
+
+- VR requires consistent frame times
+- Single dropped frame = visible judder
+- 90 FPS = 11.11ms budget
+
+---
+
+## 4. Interaction Principles
+
+### Controller Interaction
+
+| Type | Use |
+|------|-----|
+| **Point + click** | UI, distant objects |
+| **Grab** | Manipulation |
+| **Gesture** | Magic, special actions |
+| **Physical** | Throwing, swinging |
+
+### Hand Tracking
+
+- More immersive but less precise
+- Good for: social, casual
+- Challenging for: action, precision
+
+---
+
+## 5. Spatial Design
+
+### World Scale
+
+- 1 unit = 1 meter (critical)
+- Objects must feel right size
+- Test with real measurements
+
+### Depth Cues
+
+| Cue | Importance |
+|-----|------------|
+| Stereo | Primary depth |
+| Motion parallax | Secondary |
+| Shadows | Grounding |
+| Occlusion | Layering |
+
+---
+
+## 6. Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|----------|-------|
+| Move camera without player | Player controls camera |
+| Drop below 90 FPS | Maintain frame rate |
+| Use tiny UI text | Large, readable text |
+| Ignore arm length | Scale to player reach |
+
+---
+
+> **Remember:** Comfort is not optional. Sick players don't play.
+
+## When to Use
+This skill is applicable to execute the workflow or actions described in the overview.
+
+## Limitations
+- Use this skill only when the task clearly matches the scope described above.
+- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
+- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.

package/skills/game-development/web-games/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: web-games
+description: "Web browser game development principles. Framework selection, WebGPU, optimization, PWA."
+risk: unknown
+source: community
+date_added: "2026-02-27"
+---
+
+# Web Browser Game Development
+
+> Framework selection and browser-specific principles.
+
+---
+
+## 1. Framework Selection
+
+### Decision Tree
+
+```
+What type of game?
+│
+├── 2D Game
+│   ├── Full game engine features? → Phaser
+│   └── Raw rendering power? → PixiJS
+│
+├── 3D Game
+│   ├── Full engine (physics, XR)? → Babylon.js
+│   └── Rendering focused? → Three.js
+│
+└── Hybrid / Canvas
+    └── Custom → Raw Canvas/WebGL
+```
+
+### Comparison (2025)
+
+| Framework | Type | Best For |
+|-----------|------|----------|
+| **Phaser 4** | 2D | Full game features |
+| **PixiJS 8** | 2D | Rendering, UI |
+| **Three.js** | 3D | Visualizations, lightweight |
+| **Babylon.js 7** | 3D | Full engine, XR |
+
+---
+
+## 2. WebGPU Adoption
+
+### Browser Support (2025)
+
+| Browser | Support |
+|---------|---------|
+| Chrome | ✅ Since v113 |
+| Edge | ✅ Since v113 |
+| Firefox | ✅ Since v131 |
+| Safari | ✅ Since 18.0 |
+| **Total** | **~73%** global |
+
+### Decision
+
+- **New projects**: Use WebGPU with WebGL fallback
+- **Legacy support**: Start with WebGL
+- **Feature detection**: Check `navigator.gpu`
+
+---
+
+## 3. Performance Principles
+
+### Browser Constraints
+
+| Constraint | Strategy |
+|------------|----------|
+| No local file access | Asset bundling, CDN |
+| Tab throttling | Pause when hidden |
+| Mobile data limits | Compress assets |
+| Audio autoplay | Require user interaction |
+
+### Optimization Priority
+
+1. **Asset compression** - KTX2, Draco, WebP
+2. **Lazy loading** - Load on demand
+3. **Object pooling** - Avoid GC
+4. **Draw call batching** - Reduce state changes
+5. **Web Workers** - Offload heavy computation
+
+---
+
+## 4. Asset Strategy
+
+### Compression Formats
+
+| Type | Format |
+|------|--------|
+| Textures | KTX2 + Basis Universal |
+| Audio | WebM/Opus (fallback: MP3) |
+| 3D Models | glTF + Draco/Meshopt |
+
+### Loading Strategy
+
+| Phase | Load |
+|-------|------|
+| Startup | Core assets, <2MB |
+| Gameplay | Stream on demand |
+| Background | Prefetch next level |
+
+---
+
+## 5. PWA for Games
+
+### Benefits
+
+- Offline play
+- Install to home screen
+- Full screen mode
+- Push notifications
+
+### Requirements
+
+- Service worker for caching
+- Web app manifest
+- HTTPS
+
+---
+
+## 6. Audio Handling
+
+### Browser Requirements
+
+- Audio context requires user interaction
+- Create AudioContext on first click/tap
+- Resume context if suspended
+
+### Best Practices
+
+- Use Web Audio API
+- Pool audio sources
+- Preload common sounds
+- Compress with WebM/Opus
+
+---
+
+## 7. Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|----------|-------|
+| Load all assets upfront | Progressive loading |
+| Ignore tab visibility | Pause when hidden |
+| Block on audio load | Lazy load audio |
+| Skip compression | Compress everything |
+| Assume fast connection | Handle slow networks |
+
+---
+
+> **Remember:** Browser is the most accessible platform. Respect its constraints.
+
+## When to Use
+This skill is applicable to execute the workflow or actions described in the overview.
+
+## Limitations
+- Use this skill only when the task clearly matches the scope described above.
+- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
+- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.

package/skills/game-engine/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: game-engine
+description: 'Expert skill for building web-based game engines and games using HTML5, Canvas, WebGL, and JavaScript. Use when asked to create games, build game engines, implement game physics, handle collision detection, set up game loops, manage sprites, add game controls, or work with 2D/3D rendering. Covers techniques for platformers, breakout-style games, maze games, tilemaps, audio, multiplayer via WebRTC, and publishing games.'
+version: 1.0.0
+---
+
+# Game Engine Skill
+
+Build web-based games and game engines using HTML5 Canvas, WebGL, and JavaScript. This skill includes starter templates, reference documentation, and step-by-step workflows for 2D and 3D game development with frameworks such as Phaser, Three.js, Babylon.js, and A-Frame.
+
+## When to Use This Skill
+
+- Building a game engine or game from scratch using web technologies
+- Implementing game loops, physics, collision detection, or rendering
+- Working with HTML5 Canvas, WebGL, or SVG for game graphics
+- Adding game controls (keyboard, mouse, touch, gamepad)
+- Creating 2D platformers, breakout-style games, maze games, or 3D experiences
+- Working with tilemaps, sprites, or animations
+- Adding audio to web games
+- Implementing multiplayer features with WebRTC or WebSockets
+- Optimizing game performance
+- Publishing and distributing web games
+
+## Prerequisites
+
+- Basic knowledge of HTML, CSS, and JavaScript
+- A modern web browser with Canvas/WebGL support
+- A text editor or IDE
+- Optional: Node.js for build tooling and local development servers
+
+## Core Concepts
+
+The following concepts form the foundation of every web-based game engine.
+
+### Game Loop
+
+Every game engine revolves around the game loop -- a continuous cycle of:
+
+1. **Process Input** - Read keyboard, mouse, touch, or gamepad input
+2. **Update State** - Update game object positions, physics, AI, and logic
+3. **Render** - Draw the current game state to the screen
+
+Use `requestAnimationFrame` for smooth, browser-optimized rendering.
+
+### Rendering
+
+- **Canvas 2D** - Best for 2D games, sprite-based rendering, and tilemaps
+- **WebGL** - Hardware-accelerated 3D and advanced 2D rendering
+- **SVG** - Vector-based graphics, good for UI elements
+- **CSS** - Useful for DOM-based game elements and transitions
+
+### Physics and Collision Detection
+
+- **2D Collision Detection** - AABB, circle, and SAT-based collision
+- **3D Collision Detection** - Bounding box, bounding sphere, and raycasting
+- **Velocity and Acceleration** - Basic Newtonian physics for movement
+- **Gravity** - Constant downward acceleration for platformers
+
+### Controls
+
+- **Keyboard** - Arrow keys, WASD, and custom key bindings
+- **Mouse** - Click, move, and pointer lock for FPS-style controls
+- **Touch** - Mobile touch events and virtual joysticks
+- **Gamepad** - Gamepad API for controller support
+
+### Audio
+
+- **Web Audio API** - Programmatic sound generation and spatial audio
+- **HTML5 Audio** - Simple audio playback for music and sound effects
+
+## Step-by-Step Workflows
+
+### Creating a Basic 2D Game
+
+1. Set up an HTML file with a `<canvas>` element
+2. Get the 2D rendering context
+3. Implement the game loop using `requestAnimationFrame`
+4. Create game objects with position, velocity, and size properties
+5. Handle keyboard/mouse input for player control
+6. Implement collision detection between game objects
+7. Add scoring, lives, and win/lose conditions
+8. Add sound effects and music
+
+### Building a 3D Game
+
+1. Choose a framework (Three.js, Babylon.js, A-Frame, or PlayCanvas)
+2. Set up the scene, camera, and renderer
+3. Load or create 3D models and textures
+4. Implement lighting and shaders
+5. Add physics and collision detection
+6. Implement player controls and camera movement
+7. Add audio and visual effects
+
+### Publishing a Game
+
+1. Optimize assets (compress images, minify code)
+2. Test across browsers and devices
+3. Choose distribution platform (web, app stores, game portals)
+4. Implement monetization if needed
+5. Promote through game communities and social media
+
+## Game Templates
+
+Starter templates are available in the `assets/` folder. Each template provides a complete, working example that can be used as a starting point for a new project.
+
+| Template | Description |
+|----------|-------------|
+| `paddle-game-template.md` | 2D Breakout-style game with pure JavaScript |
+| `2d-maze-game.md` | Maze game with device orientation controls |
+| `2d-platform-game.md` | Platformer game using Phaser framework |
+| `gameBase-template-repo.md` | Game base template repository structure |
+| `simple-2d-engine.md` | Simple 2D platformer engine with collisions |
+
+## Reference Documentation
+
+Detailed reference material is available in the `references/` folder. Consult these files for in-depth coverage of specific topics.
+
+| Reference | Topics Covered |
+|-----------|---------------|
+| `basics.md` | Game development introduction and anatomy |
+| `web-apis.md` | Canvas, WebGL, Web Audio, Gamepad, and other web APIs |
+| `techniques.md` | Collision detection, tilemaps, async scripts, audio |
+| `3d-web-games.md` | 3D theory, frameworks, shaders, WebXR |
+| `game-control-mechanisms.md` | Touch, keyboard, mouse, and gamepad controls |
+| `game-publishing.md` | Distribution, promotion, and monetization |
+| `algorithms.md` | Raycasting, collision, physics, vector math |
+| `terminology.md` | Game development glossary |
+| `game-engine-core-principles.md` | Core design principles for game engines |
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| Canvas is blank | Check that you are calling drawing methods after getting the context and inside the game loop |
+| Game runs at different speeds | Use delta time in update calculations instead of fixed values |
+| Collision detection is inconsistent | Use continuous collision detection or reduce time steps for fast-moving objects |
+| Audio does not play | Browsers require user interaction before playing audio; trigger playback from a click handler |
+| Performance is poor | Profile with browser dev tools, reduce draw calls, use object pooling, and optimize asset sizes |
+| Touch controls are unresponsive | Prevent default touch behavior and handle touch events separately from mouse events |
+| WebGL context lost | Handle the `webglcontextlost` event and restore state on `webglcontextrestored` |