@evitcastudio/kit 3.3.1 → 3.4.0

package/README.md

@@ -1,27 +1,80 @@
-# Kit
+<p align="center">
+  <img src="./evitcastudio_round_branding.png" width="128" height="128" alt="Evitca Studio Logo" />
+</p>
 
-**Kit** is a lightweight, extensible 2D framework for game development in the [Vylocity Game Engine](https://www.vylocity.com/). Designed to be simple and modular, Kit empowers developers to build complex projects quickly through a robust plugin-driven architecture.
+<h1 align="center">@evitcastudio/kit</h1>
+
+<p align="center">
+  A lightweight, extensible framework and developer toolkit for the Vylocity Game Engine.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@evitcastudio/kit"><img src="https://img.shields.io/npm/v/@evitcastudio/kit.svg?color=10b981" alt="npm version" /></a>
+  <a href="https://github.com/EvitcaStudio/Kit/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License" /></a>
+  <a href="https://github.com/EvitcaStudio/Kit"><img src="https://img.shields.io/badge/TypeScript-Ready-3178c6.svg" alt="TypeScript" /></a>
+</p>
+
+---
+
+## Features
+
+- **Modular Plugin Architecture**: Centralized service locator (`Kit.registerPlugin`, `Kit.getPlugin`) with lifecycle hooks and a decoupled typed event bus (`Kit.on`, `Kit.off`).
+- **Official Plugins Included**:
+  - **`Camera` (Lens)**: 5 specialized camera types (`Follow`, `Pan`, `Spectate`, `Influence`, `Transition`), 29 shake presets, smooth zoom, zero-pop transitions, and native 2D canvas debug overlays.
+  - **`Network`**: Structured client-server packet communication with registered names and automatic indexing for bandwidth optimization.
+- **Developer CLI (`kit`)**:
+  - **`kit init`**: Interactive scaffolding for Singleplayer and Multiplayer game templates.
+  - **`kit build`**: Zero-config compilation, asset hashing (`.vyr`), metadata manifest generation, and production minification/obfuscation.
+  - **`kit host`**: Built-in local HTTP and game server hosting with hot-reloading and LAN network URLs.
+  - **`kit create`**: Instant boilerplate generator for typed plugins.
+  - **`kit doctor`**: Comprehensive environment and project health diagnostics.
+- **Smart Asset Pipeline**: Fast hashing, automatic passthrough for subdirectories, and automatic metadata manifest generation (`resource.json`, `bounds.json`, `sizes.json`, `icon-points.json`).
+- **Zero-Config TypeScript**: Powered by Bun for blazing fast bundling, incremental watch mode, and complete type safety.
+
+---
 
 ## Installation
 
 ```bash
+# Global CLI installation (recommended)
 bun install -g @evitcastudio/kit
+
+# Or as a project dependency
+bun add @evitcastudio/kit
+```
+
+---
+
+## Quickstart
+
+```bash
+# 1. Initialize a new project
+kit init my-game --single --install
+
+# 2. Build game and assets
+cd my-game && kit build
+
+# 3. Host locally
+kit host
 ```
-> **Note:** The `-g` flag ensures the `kit` CLI tool is globally available in your PATH.
+
+Your game will immediately be accessible at `http://localhost:8090` (or `http://localhost:30000` for multiplayer).
+
+---
 
 ## CLI Reference & Usage
 
-Kit includes a CLI tool (`kit`) for scaffolding projects, building game assets, generating plugin boilerplate, and diagnosing your environment.
+Kit includes the `kit` CLI for scaffolding, asset compilation, boilerplate generation, and local testing.
 
 ### Global Options
 - `-v, --verbose`: Enables verbose output and detailed debugging logs.
-- `-h, --help`: Displays help and usage information for any command.
+- `-h, --help`: Displays help and usage information.
 - `-V, --version`: Displays the installed Kit CLI version.
 
 ---
 
 ### `kit init [name]`
-Initializes a new game project for the Vylocity Game Engine. If run without arguments or flags, an interactive prompt will guide you through project setup.
+Initializes a new game project. Run without arguments for an interactive setup prompt.
 
 ```bash
 # Interactive setup
@@ -31,195 +84,224 @@ kit init
 kit init my-game --single --install
 ```
 
-#### Flags & Options:
-| Flag / Option | Type | Default | Description |
-| :--- | :--- | :--- | :--- |
-| `[name]` | `string` | `kit-project` | The name of the project folder to create. |
-| `-s, --single` | `boolean` | `false` | Quick-starts a single-player game template. |
-| `-m, --multi` | `boolean` | `false` | Quick-starts a multiplayer game template (pass both `-s` and `-m` for both). |
-| `-f, --force` | `boolean` | `false` | Overwrites the destination folder if it already exists without aborting. |
-| `-i, --install` | `boolean` | `false` | Automatically runs `bun install` inside the new project directory after creation. |
+| Option | Description | Default |
+| :--- | :--- | :--- |
+| `[name]` | Project folder name. | `kit-project` |
+| `-s, --single` | Scaffolds a single-player game template. | `false` |
+| `-m, --multi` | Scaffolds a multiplayer game template. | `false` |
+| `-f, --force` | Overwrites destination folder if it already exists. | `false` |
+| `-i, --install` | Automatically runs `bun install` after scaffolding. | `false` |
 
 ---
 
 ### `kit build`
-Builds resources and compiles game application code. Automatically detects whether your project is **Singleplayer** or **Multiplayer**, compiles TypeScript entrypoints to `dist/`, copies static web files (`.html`, `.css`, `.ico`, vendor directories), hashes raw assets into unique identifiers (`.vyr`), mirrors custom subdirectories, and exports metadata manifests (`resource.json`, `bounds.json`, `icon-points.json`, and `sizes.json`).
+Compiles TypeScript application code to `dist/`, hashes raw assets into unique identifiers (`.vyr`), mirrors asset subdirectories, and generates metadata manifests.
 
 ```bash
-# Zero-config build (auto-detects project architecture, builds ./src to ./dist)
+# Zero-config build (auto-detects project architecture)
 kit build
 
-# Production ready build (minified, obfuscated identifiers, stripped sourcemaps)
-kit build -p
-
-# Watch mode: auto-rebuilds on source or resource changes
+# Watch mode (incremental rebuilds on source or resource changes)
 kit build --watch
 
-# Build only raw resources with custom directories
-kit build -i ./src/resources -o ./dist --no-app
-
-# Save the resource manifest to a custom location
-kit build --manifest ./dist/resource.json
-```
-
-#### Flags & Options:
-| Flag / Option | Type | Required | Default | Description |
-| :--- | :--- | :--- | :--- | :--- |
-| `-i, --in <path>` | `string` | No | `./src/resources` | Input directory containing raw game assets (`.vyi`, `.vym`, `.vyint`, audio, etc.). |
-| `-o, --out <path>` | `string` | No | `./dist` | Destination directory where processed `resources/` and bundled app files will be written. |
-| `-m, --manifest <path>` | `string` | No | `./resource.json` | Path where the resource lookup JSON should be saved. If omitted, defaults to `./resource.json` in the current working directory. |
-| `-w, --watch` | `boolean` | No | `false` | Watches the source and resource directories for changes and triggers automatic incremental rebuilds. |
-| `-is, --ignore-sound` | `boolean` | No | `false` | Skips processing and copying sound and music files (`.mp3`, `.ogg`, `.wav`, etc.). |
-| `-p, --prod` | `boolean` | No | `false` | Production mode: enables full minification, identifier obfuscation/mangling, and strips sourcemaps. |
-| `--minify` | `boolean` | No | `false` | Minifies bundled JavaScript syntax, whitespace, and variable names. |
-| `--obfuscate` | `boolean` | No | `false` | Mangles and obfuscates identifiers across bundled output. |
-| `--sourcemap <mode>` | `string` | No | `linked` (`none` in prod) | Sourcemap mode (`none`, `linked`, `inline`, `external`). |
-| `--app` / `--no-app` | `boolean` | No | `true` (auto) | Toggles application code bundling. Enabled automatically if `src/index.ts` or `src/client/index.ts` exists. |
-
-#### What is the Resource Manifest (`resource.json`)?
-A manifest is an index or lookup table. `kit build` obfuscates asset names into unique identifiers (`uuid.vyr`) as a security benefit to protect and hide original asset filenames in production. It generates `resource.json` mapping your original human-readable asset names to their engine identifiers:
-```json
-{
-    "icon": [
-        {
-            "fileName": "player.vyi",
-            "resourceIdentifier": "3cf72322-6b92-4ea5-bbca-b96fae1fe440.vyr"
-        }
-    ],
-    "map": [ ... ],
-    "sound": [ ... ]
-}
-```
-
-#### Custom Asset Subdirectories (Automatic Pass-Through)
-Any subdirectories inside your resource folder (e.g. `src/resources/images`, `src/resources/fonts`, `src/resources/emitters`, `src/resources/particles`, etc.) are automatically mirrored to `<out>/resources/<folder>/`. Non-engine files remain in their original form.
-
----
-
-### `kit create <type> <name>`
-Scaffolds boilerplate files inside an existing Kit project following standard architectural conventions.
-
-```bash
-# Generate a typed plugin
-kit create plugin Inventory
+# Production build (minified, obfuscated identifiers, stripped sourcemaps)
+kit build -p
 ```
 
-#### Types:
-- `plugin`: Creates a new TypeScript file at `src/plugins/<name>.ts` that subclasses `KitPlugin` with typed lifecycle hooks (`onRegistered()`) ready to extend.
+| Option | Description | Default |
+| :--- | :--- | :--- |
+| `-i, --in <path>` | Input resource directory containing raw game assets. | `./src/resources` |
+| `-o, --out <path>` | Output directory for processed assets and bundled code. | `./dist` |
+| `-m, --manifest <path>` | Custom destination path for `resource.json`. | `./resource.json` |
+| `-w, --watch` | Watches source and resource folders for auto-rebuilding. | `false` |
+| `-p, --prod` | Production mode (minification, mangled identifiers, no maps). | `false` |
+| `--minify` / `--obfuscate` | Granular syntax minification or identifier mangling. | `false` |
+| `--sourcemap <mode>` | Sourcemap mode (`none`, `linked`, `inline`, `external`). | `linked` |
+| `--app` / `--no-app` | Toggles application code bundling. | `true` |
+
+#### Generated Metadata Manifests
+During build, Kit produces optimized metadata indices in your project:
+- **`resource.json`**: Maps original human-readable asset filenames to obfuscated engine identifiers (`uuid.vyr`).
+- **`bounds.json` & `sizes.json`**: Pre-calculated collision boundaries and dimensions for icons and tiles.
+- **`icon-points.json`**: Defined anchor points and equipment attachment coordinates for sprites.
 
 ---
 
 ### `kit host`
-Hosts the game project locally for development and testing.
+Hosts your compiled game project locally for browser or multiplayer testing.
 
 ```bash
-# Host the dist folder on port 8090
+# Host dist folder on default port 8090
 kit host
 
 # Build before hosting and specify custom port
 kit host -b -p 8080
 ```
 
-#### Options:
-- `-p, --port <number>`: Port to bind the server to (default: `8090`).
-- `-d, --dir <path>`: Directory containing built files to serve (default: `./dist`).
-- `-b, --build`: Trigger a `kit build` before starting the server.
+| Option | Description | Default |
+| :--- | :--- | :--- |
+| `-p, --port <number>` | Port to bind the server to. | `8090` |
+| `-d, --dir <path>` | Directory of built files to serve. | `./dist` |
+| `-b, --build` | Runs `kit build` prior to starting server. | `false` |
 
-#### Behavior:
-- **Singleplayer / Client Projects:** Spawns a lightweight local HTTP server powered by Bun that serves `dist/index.html` and static assets with local and network LAN URLs.
-- **Multiplayer Projects:** Automatically launches the backend node server (`dist/server.js`) with configured settings (`dist/settings.json`).
+---
+
+### `kit create <type> <name>`
+Scaffolds typed boilerplate into an existing Kit project.
+
+```bash
+kit create plugin Inventory
+```
+Generates `src/plugins/inventory.ts` subclassing `KitPlugin` with lifecycle hooks ready to extend.
 
 ---
 
 ### `kit doctor`
-Inspects your local environment and current project health.
+Inspects your local environment and project health (Bun runtime, Git availability, `package.json`, project architecture, and build pipeline).
 
 ```bash
 kit doctor
 ```
 
-#### What it checks:
-- **Bun Runtime:** Verifies that Bun is installed and detects the version.
-- **Git Installation:** Verifies that Git is accessible in your `PATH`.
-- **Project Structure:** If executed within a game project, checks `package.json`, `@evitcastudio/kit` framework dependencies, and asset folders (`src/resources`).
-- **Project Architecture:** Detects whether the project is **Singleplayer** (`src/index.ts`), **Multiplayer** (`src/client` & `src/server`), or **Dedicated Server**.
-- **Build Pipeline:** Verifies that a valid build pipeline is configured (either native `kit build` in `package.json` or legacy `bun-build.ts`).
-
 ---
 
 ## Runtime Resource Loading
 
-> **Note:** This process is preconfigured for you if you used `kit init`.
-
-`Kit.setResources()` should be called **before** `VYLO.load()`.
+`Kit.setResources()` loads the generated `resource.json` manifest into the Vylocity engine prior to calling `VYLO.load()`:
 
 ```typescript
 import resourceJSON from 'resource.json';
 
-// Initialize the engine with mapped resources
+// Initialize engine with mapped resource identifiers
 await Kit.setResources(resourceJSON);
+await VYLO.load();
 ```
 
+---
 
-## Local Development & Testing
+## Plugins
 
-Once your project is scaffolded and dependencies are installed and the project has been built, you can run your game locally.
+Kit features a modular plugin architecture. Plugins register via `Kit.registerPlugin()`, are retrievable globally through `Kit.getPlugin(name)`, and communicate across decoupled systems using Kit's typed event bus.
 
-### Running the Game
+```typescript
+import { Kit } from '@evitcastudio/kit';
+import { CustomPlugin } from 'custom-plugin';
 
-```bash
-# For Single-Player or Multiplayer games
-bun run host
+// Register with Kit
+const plugin = Kit.registerPlugin(CustomPlugin);
+
+// Retrieve anywhere by plugin name
+const plugin = Kit.getPlugin<CustomPlugin>('CustomPlugin');
+```
+
+---
+
+### Official Plugins
+
+#### 1. Camera Plugin (`Camera` / `@evitcastudio/lens`)
+High-performance 2D camera system powered by [`@evitcastudio/lens`](https://github.com/EvitcaStudio/Lens). Supports 5 specialized camera types, 29 shake presets, smooth zoom, zero-pop transitions, native canvas debug overlays, and automatic event dispatching.
+
+##### Setup & Quickstart
+
+```typescript
+import { Kit, Camera } from '@evitcastudio/kit';
+
+// 1. Register with Kit (indexes under name 'Camera')
+const camera = Kit.registerPlugin(Camera);
+
+// 2. Track player entity with smooth lerping & deadzone
+camera.createFollowCamera('main', playerMob, {
+    lerp: 0.1,
+    deadzone: { width: 64, height: 64 }
+});
 ```
 
-### Accessing the Game
+##### Seamless Transitions
+Blend smoothly between cameras or targets with Hermite spline interpolation and spring-damping (zero visual pop):
 
-The server will be available at the following locations after being hosted:
+```typescript
+await camera.switchTo(bossCamera, {
+    duration: 800,
+    smoothing: 'smoothDamp', // or 'cubicSpline'
+    springTension: 170,
+    springFriction: 26
+});
+```
 
-> **Singleplayer**  
-[http://localhost:8090](http://localhost:8090) defined in `./bun-serve.ts`
+##### Screen Shake & Zoom
+```typescript
+// Trigger built-in presets or infinite ambient shakes
+camera.shakePreset('explosion-large');
+camera.shakePreset('rumble', undefined, true);
 
-> **Multiplayer or Singleplayer & Multiplayer**  
-[http://localhost:30000](http://localhost:30000) defined in `./src/server/settings.json`
+// Smooth zoom animations with 30+ easing equations
+camera.zoom(2, 500, 'easeOutCubic');
+camera.zoom(1, 400, 'easeInOutQuad'); // Reset
+```
 
+##### Camera Event Bus
+All camera lifecycle events automatically dispatch to Kit's global event bus (`Kit.on`), allowing audio, gamepad vibration, or UI systems to decouple from camera logic:
 
-## Plugin Architecture
+```typescript
+Kit.on('Camera', 'shake-start', (event) => {
+    console.log('Camera shaking:', event.data.preset);
+});
 
-```ts
-import { Plugin } from 'custom-plugin';
+Kit.on('Camera', 'transition-start', () => {
+    // e.g. animate cinematic bars
+});
+```
+
+##### Native Debug Overlay & Gizmos
+Built-in 2D canvas overlay for debugging cameras, bounds, target vectors, and crosshairs:
 
-// Register a single plugin
-const plugin = Kit.registerPlugin(Plugin);
+```typescript
+camera.setDebugMode({
+    enabled: true,
+    showCameraMarkers: true,
+    showTargetLines: true,
+    showBounds: true,
+    showCenterCrosshair: true,
+    bounds: { minX: 0, maxX: 2000, minY: 0, maxY: 2000 }
+});
 ```
 
-```ts
-// Register multiple plugins
-import { Plugin1 } from 'custom-plugin1';
-import { Plugin2 } from 'custom-plugin2';
+---
+
+#### 2. Network Plugin (`Network`)
+Handles client-server packet communication with registered packet names, automatic indexing, and minimal bandwidth usage.
+
+```typescript
+import { Kit, Network } from '@evitcastudio/kit';
 
-const plugins = Kit.registerPlugins([Plugin1, Plugin2]);
+const network = Kit.registerPlugin(Network);
 
-// After being registered, kit can find the plugin by name.
-const plugin1 = Kit.getPlugin('plugin1-name');
-const plugin2 = Kit.getPlugin('plugin2-name');
+// Client-side: register server packet definitions & listen
+network.registerPackets(['CHAT_MESSAGE', 'PLAYER_HEAL'] as const);
+
+network.on('CHAT_MESSAGE', (client, senderName, message) => {
+    console.log(`[${senderName}]: ${message}`);
+});
 ```
 
-### Listening for plugin events
+---
 
-Plugins emit events, this is how they pass relevant data to other plugins or the main thread.
-By listening to these events you can act on this data.
+### Plugin Events
 
-```js
-const listener = (pEvent: EmitterEvent) => {
-    const { data, timestamp } = pEvent;
-    // Here you can use the data that the event sent down.
-}
+Plugins can emit and listen to events across the entire application:
 
-// Choose to listen to specific event from a plugin
-Kit.on('plugin-name', 'event-name', listener);
+```typescript
+// Listen for an event from any plugin
+Kit.on('plugin-name', 'event-name', (event) => {
+    console.log(event.data, event.timestamp);
+});
 
-// You can also stop listening for an event
+// Remove listener
 Kit.off('plugin-name', 'event-name', listener);
 ```
 
-For more information check out the [wiki](https://github.com/EvitcaStudio/Kit/wiki)
+---
+
+## License
+
+MIT © [Evitca Studio](https://evitcastudio.com) & [doubleactii](https://github.com/doubleactii)