kustom-mc 0.1.0

package/README.md

@@ -0,0 +1,809 @@
+# Kustom MC
+
+CLI and type library for developing kustompack scripts with TypeScript support.
+
+## Installation
+
+```bash
+npm install kustom-mc
+# or
+npx kustom-mc <command>
+```
+
+## Quick Start
+
+```bash
+# Create a new project
+npx kustom-mc init my-pack
+
+# Build scripts
+npx kustom-mc build
+
+# Build and watch for changes
+npx kustom-mc build --watch
+
+# Build and deploy to server
+npx kustom-mc build --deploy
+```
+
+## Table of Contents
+
+- [Script Format](#script-format)
+- [Props System](#props-system)
+- [Importing Scripts](#importing-scripts)
+- [Screen GUI System](#screen-gui-system)
+- [Containers & Layouts](#containers--layouts)
+- [Elements](#elements)
+- [Chat GUI System](#chat-gui-system)
+- [Camera System](#camera-system)
+- [Custom Blocks (Shaper)](#custom-blocks-shaper)
+- [Custom Items](#custom-items)
+- [BetterModel Entities](#bettermodel-entities)
+- [Commands](#commands)
+- [Configuration](#configuration)
+
+---
+
+## Script Format
+
+Scripts use the `defineScript` helper for type safety:
+
+```typescript
+import { defineScript, Props } from "kustom-mc";
+
+export default defineScript({
+  props: {
+    player: Props.String(),
+    message: Props.String("Hello!"),
+    count: Props.Number(1),
+  },
+
+  run({ process, props, executor }) {
+    const player = process.getPlayer(props.player);
+    player.sendMessage(props.message);
+    
+    // Access process methods via `this` or `process`
+    this.exit("done");
+  },
+});
+```
+
+### Script Context
+
+The `run` function receives a context object with:
+
+| Property | Description |
+|----------|-------------|
+| `process` | Process API for script management |
+| `props` | Validated props passed to the script |
+| `executor` | Who executed the script (player or console) |
+| `camera` | Camera system for cinematic views |
+| `session` | Chat session system |
+| `chatGUI` | Chat GUI system |
+| `command` | Command registration |
+| `entity` | BetterModel entity system |
+| `shaper` | Custom block system |
+| `items` | Custom item system |
+
+The `this` context is also the process, allowing:
+```typescript
+this.exit(value);      // Exit with return value
+this.emit("event");    // Emit event to parent
+this.getPlayer(name);  // Get player by name
+```
+
+---
+
+## Props System
+
+Define typed properties for your scripts:
+
+```typescript
+import { defineScript, Props } from "kustom-mc";
+
+export default defineScript({
+  props: {
+    // Required string (no default)
+    player: Props.String(),
+    
+    // String with default
+    title: Props.String("Welcome"),
+    
+    // Number with default
+    amount: Props.Number(100),
+    
+    // Boolean with default
+    enabled: Props.Boolean(true),
+    
+    // Object/Array
+    data: Props.Object({}),
+    items: Props.Array([]),
+    
+    // Union type (one of these values)
+    mode: Props.Union("easy", "normal", "hard"),
+  },
+
+  run({ props }) {
+    console.log(props.player);  // string
+    console.log(props.amount);  // number
+    console.log(props.enabled); // boolean
+  },
+});
+```
+
+---
+
+## Typed Events System
+
+Scripts can declare typed events for type-safe communication between parent and child scripts:
+
+```typescript
+// digicode.ts
+import { defineScript, Props } from "kustom-mc";
+
+export default defineScript({
+  props: {
+    player: Props.String(),
+    code: Props.String("1234"),
+  },
+
+  // Declare events with typed payloads
+  events: {
+    onSuccess: Props.Boolean(),  // Event with boolean payload
+    onUnlock: Props.String(),    // Event with string payload
+  },
+
+  run({ process, props }) {
+    // Emit typed events - TypeScript checks payload types!
+    process.emit("onSuccess", true);      // OK
+    process.emit("onUnlock", "1234");     // OK
+    // process.emit("onSuccess", "wrong"); // TS Error: expected boolean
+    // process.emit("unknown", true);      // TS Error: unknown event
+  },
+});
+```
+
+```typescript
+// main.ts
+import { defineScript, Props } from "kustom-mc";
+import digicode from "./digicode";
+
+export default defineScript({
+  props: {
+    player: Props.String(),
+  },
+
+  run({ process, props }) {
+    const child = digicode.run({
+      player: props.player,
+      code: "1234",
+    });
+
+    // TypeScript infers callback parameter types from digicode's events!
+    child.on("onSuccess", (value) => {
+      // value is typed as boolean
+      console.log("Code accepted!", value);
+    });
+
+    child.on("onUnlock", (code) => {
+      // code is typed as string
+      console.log("Entered code:", code);
+    });
+
+    // Use then() for exit handling (not events)
+    child.then((result) => {
+      console.log("Child exited with:", result);
+    });
+  },
+});
+```
+
+### Event Methods
+
+Scripts without `events` declaration still work - events are untyped (backward compatible).
+
+```typescript
+const child = otherScript.run({ ...props });
+
+// Listen for events
+child.on("eventName", (value) => {});    // Listen for event
+child.once("eventName", (value) => {});  // Listen once, auto-remove after first call
+child.off("eventName", callback);         // Remove specific listener
+child.off("eventName");                   // Remove all listeners for event
+```
+
+### Multiple Listeners
+
+Multiple listeners can be registered for the same event:
+
+```typescript
+child.on("onSuccess", () => console.log("First handler"));
+child.on("onSuccess", () => console.log("Second handler"));
+// Both handlers are called when onSuccess is emitted
+```
+
+---
+
+## Importing Scripts
+
+Scripts can import and run other scripts:
+
+### ScriptProcess API
+
+When running an imported script, you get a `ScriptProcess`:
+
+```typescript
+const child = otherScript.run({ ...props });
+
+child.on("eventName", (value) => {});    // Listen for events (typed if declared)
+child.once("eventName", (value) => {});  // Listen once (auto-remove)
+child.off("eventName", callback);         // Remove specific listener
+child.off("eventName");                   // Remove all listeners for event
+child.emit("eventName", ...args);         // Send event to child
+child.call("methodName", ...args);        // Call method on child
+child.then((result) => {});               // Handle completion
+child.catch((error) => {});               // Handle errors
+child.getId();                            // Get process ID
+child.hasExited();                        // Check if completed
+```
+
+---
+
+## Screen GUI System
+
+Create inventory-based GUIs:
+
+```typescript
+import { defineScript, Screen, Props } from "kustom-mc";
+
+export default defineScript({
+  props: { player: Props.String() },
+
+  run({ process, props }) {
+    const player = process.getPlayer(props.player);
+
+    // Create a 27-slot screen (3 rows)
+    const screen = new Screen(27, {
+      hidePlayerInventory: true,  // Hide player's items
+      autoCover: true,            // Auto-fill empty slots
+    });
+
+    // Or with custom texture
+    const texturedScreen = new Screen("my_gui", 54);
+
+    // Add text overlay
+    const title = screen.appendText("My GUI", 12, -30, true);
+
+    // Add buttons
+    screen.addButton(13, "confirm_button", "Click me!", (event) => {
+      console.log("Button clicked!");
+      event.cancel();  // Prevent item pickup
+    });
+
+    // Handle events
+    screen.on("open", (p) => console.log(p.getName() + " opened"));
+    screen.on("close", (p) => {
+      process.exit(null);
+    });
+
+    // Open for player
+    screen.open(player);
+  },
+});
+```
+
+### Screen Options
+
+```typescript
+new Screen(size, {
+  hidePlayerInventory: boolean,     // Store and hide player inventory
+  playerInventoryEnabled: boolean,  // Allow inventory interaction
+  usePlayerInventorySlots: boolean, // Use player inv for buttons
+  autoCover: boolean,               // Cover empty slots
+  coverTexture: string,             // Custom cover texture
+  persistenceKey: string,           // Enable persistence
+});
+```
+
+### Player Inventory Slots
+
+Use player inventory slots for extended GUIs (like numpad):
+
+```typescript
+const screen = new Screen(9, {
+  usePlayerInventorySlots: true,  // Enable player inv slots
+  autoCover: false,
+});
+
+// Chest slots: 0-8 (for 9-slot screen)
+// Player inventory slots: 54-89
+// Mapping: main inv (9-35) -> 54-80, hotbar (0-8) -> 81-89
+
+screen.addButton(54, "button_1", null, () => addDigit(1));
+screen.addButton(81, "confirm", null, () => confirm());
+```
+
+---
+
+## Containers & Layouts
+
+Organize elements in containers with grid or flex layouts:
+
+```typescript
+// Create a scrollable container
+const container = screen.createContainer({
+  startSlot: 10,
+  rows: 3,
+  cols: 7,
+  scrollable: true,
+  maxCapacity: 100,
+});
+
+// Add items dynamically
+for (let i = 0; i < 50; i++) {
+  container.pushButton("item_" + i, "Item " + i, (e) => {
+    console.log("Clicked item", i);
+  });
+}
+
+// Scroll controls
+screen.addButton(8, "arrow_right", "Next", () => {
+  container.scrollPage(1);
+  screen.refresh();
+});
+
+screen.addButton(0, "arrow_left", "Previous", () => {
+  container.scrollPage(-1);
+  screen.refresh();
+});
+
+// Check pagination state
+container.hasNextPage();      // boolean
+container.hasPreviousPage();  // boolean
+container.getCurrentPage();   // 0-based page number
+container.getPageCount();     // total pages
+```
+
+### Container Methods
+
+```typescript
+// Adding elements
+container.pushButton(texture, title, onClick);  // Next available slot
+container.putButton(index, texture, title, onClick);  // Specific index
+container.pushContentSlot();  // Slot for player items
+container.pushCover();        // Visual cover element
+container.pushContainer(config);  // Nested container
+
+// Layout configuration (chainable)
+container
+  .setLayout("flex")     // "grid" or "flex"
+  .setDirection("row")   // "row" or "column"
+  .setGap(1)             // Gap between items
+  .setRows(3)
+  .setCols(7);
+
+// Scrolling
+container.scroll(offset);      // Relative scroll
+container.scrollTo(index);     // Scroll to specific item
+container.scrollToPage(page);  // Go to page
+
+// Events
+container.on("scroll", (offset, page) => {});
+container.on("childAdded", (child, index) => {});
+container.on("capacityReached", () => {});
+```
+
+---
+
+## Elements
+
+Create different types of GUI elements:
+
+```typescript
+import { Element } from "kustom-mc";
+
+// Button element
+const button = Element.button("my_texture", "Button Title");
+button.onClick((e) => console.log("Clicked!"));
+button.onRightClick((e) => console.log("Right clicked!"));
+button.onShiftClick((e) => console.log("Shift clicked!"));
+
+// Display-only element (no interaction)
+const display = Element.display("info_icon");
+
+// Content slot (accepts player items)
+const slot = Element.contentSlot();
+slot.on("afterItemPlace", (item, player, index) => {
+  console.log(player.getName() + " placed " + item.getMaterialName());
+});
+slot.on("afterItemTake", (player, index) => {
+  console.log(player.getName() + " took item from slot " + index);
+});
+
+// Cover element (visual overlay)
+const cover = Element.cover();
+cover.setColor("#FF0000");  // Red cover
+```
+
+### Element Chainable Methods
+
+```typescript
+element
+  .setTexture("new_texture")
+  .setTitle("New Title")
+  .setLore(["Line 1", "Line 2"])
+  .setHideTooltip(true)
+  .setInteractive(false)
+  .setData({ custom: "data" });
+```
+
+---
+
+## Chat GUI System
+
+Create chat-based interactive UIs:
+
+```typescript
+run({ process, props, chatGUI }) {
+  const gui = chatGUI.create();
+  
+  gui.addLine((line) => {
+    line.center()
+        .background("#1a1a1a")
+        .addBoldText("Welcome!", "gold");
+  });
+  
+  gui.addEmptyLine();
+  
+  gui.addLine((line) => {
+    line.spaceBetween()
+        .addButton("[Accept]", "/accept", "Click to accept", "green")
+        .addButton("[Decline]", "/decline", "Click to decline", "red");
+  });
+  
+  gui.setBlocking(true);  // Capture chat input
+  
+  gui.onInput((playerName, message, guiId) => {
+    console.log(playerName + " typed: " + message);
+  });
+  
+  gui.open(props.player);
+}
+```
+
+### ChatGUILine Methods
+
+```typescript
+line
+  .padding(10)                    // Add padding
+  .center()                       // Center content
+  .spaceBetween()                 // Space between items
+  .background("#1a1a1a")          // Background color
+  .addText("Hello", "white")      // Add text
+  .addBoldText("Bold!", "gold")   // Bold text
+  .addButton("[Click]", "/cmd", "Hover text", "green");
+```
+
+---
+
+## Camera System
+
+Create cinematic camera views:
+
+```typescript
+run({ process, props, camera }) {
+  const player = process.getPlayer(props.player);
+  const loc = player.getLocation();
+  
+  // Create camera at player's position
+  const cam = camera.create(loc.getX(), loc.getY() + 5, loc.getZ());
+  
+  // Start spectating
+  cam.startCameraMode(props.player);
+  
+  // Camera controls
+  cam.lookAt(0, 64, 0);           // Look at coordinates
+  cam.lookAtPlayer("OtherPlayer"); // Look at player
+  cam.setRotation(90, -30);        // Set yaw/pitch
+  cam.moveTo(100, 70, 100);        // Teleport camera
+  
+  // Transparent view (see through blocks)
+  cam.setTransparentView(true);
+  
+  // Animations
+  const anim = camera.getAnimation();
+  
+  anim.createAnimation()
+    .start(0, 64, 0)
+    .end(100, 64, 100)
+    .duration(5)
+    .camera(cam.getId())
+    .onEnd(() => console.log("Animation done!"))
+    .build()
+    .start();
+  
+  // Stop spectating
+  cam.stopSpectating();
+  cam.remove();
+}
+```
+
+---
+
+## Custom Blocks (Shaper)
+
+Define custom blocks with models and collision:
+
+```typescript
+run({ process, props, shaper }) {
+  // Create block template
+  const template = shaper.create("my_block")
+    .withModel("kustom:block/my_model")
+    .fullBlockCollision()  // 1x1x1 collision
+    .onClick((event) => {
+      event.player.sendMessage("You clicked the block!");
+    })
+    .onBreak((event) => {
+      console.log("Block broken at", event.instance.getLocation());
+    })
+    .register();
+  
+  // Spawn instance
+  const loc = process.getPlayer(props.player).getLocation();
+  const instance = template.spawn(loc, 0);  // 0 = rotation degrees
+  
+  // Instance methods
+  instance.setRotation(90);
+  instance.playAnimation("open");
+  instance.setState("locked", true);
+  instance.getState("locked");  // true
+  instance.remove();
+}
+```
+
+### Block Definition File
+
+```typescript
+// blocks/tower.ts
+import { defineBlock } from "kustom-mc";
+
+export default defineBlock({
+  id: "tower",
+  model: "kustom:block/tower",
+  collision: { width: 1, height: 3, depth: 1, cornerY: 0 },
+  autoPlace: true,  // Auto-generate placement item
+  
+  onClick(event) {
+    event.player.sendMessage("Tower clicked!");
+  },
+  
+  onBreak(event) {
+    return false;  // Prevent breaking
+  },
+});
+```
+
+---
+
+## Custom Items
+
+Define custom items with events:
+
+```typescript
+// items/magic_wand.ts
+import { defineItem } from "kustom-mc";
+
+export default defineItem({
+  id: "magic_wand",
+  material: "STICK",
+  model: "kustom:item/magic_wand",
+  displayName: "<gold>Magic Wand",
+  description: "A powerful magical artifact",
+  
+  onRightClick(event) {
+    event.player.sendMessage("<rainbow>Woosh!</rainbow>");
+  },
+  
+  onLeftClick(event) {
+    // Attack with wand
+  },
+  
+  onDamageEntity(event) {
+    // Custom damage logic
+  },
+});
+```
+
+---
+
+## BetterModel Entities
+
+Spawn and control animated entities:
+
+```typescript
+run({ process, props, entity }) {
+  const loc = process.getPlayer(props.player).getLocation();
+  
+  // Spawn entity
+  const npc = entity.spawn("my_model", loc.getX(), loc.getY(), loc.getZ());
+  
+  // Play animation
+  npc.playAnimation("wave", "PLAY_ONCE");
+  npc.playAnimation("idle", "LOOP");
+  
+  // Get available animations
+  const anims = npc.getAvailableAnimations();  // ["idle", "walk", "wave"]
+  
+  // Disguise player as model
+  const disguise = entity.disguisePlayer(props.player, "npc_model");
+  disguise.playAnimation("dance");
+  
+  // Remove disguise
+  entity.undisguisePlayer(props.player);
+  
+  // Cleanup
+  npc.destroy();
+}
+```
+
+---
+
+## Commands
+
+### CLI Commands
+
+#### `kustom init [project-name]`
+
+Create a new kustompack project.
+
+```bash
+npx kustom-mc init my-pack
+npx kustom-mc init           # Initialize in current directory
+npx kustom-mc init --force   # Overwrite existing files
+```
+
+#### `kustom build`
+
+Compile TypeScript to JavaScript.
+
+```bash
+npx kustom-mc build              # Build all scripts
+npx kustom-mc build --watch      # Watch mode
+npx kustom-mc build --deploy     # Build and copy to server
+npx kustom-mc build --no-validate # Skip validation
+```
+
+#### `kustom bundle`
+
+Create a distributable zip file.
+
+```bash
+npx kustom-mc bundle                    # Create kustompack.zip
+npx kustom-mc bundle -o my-pack.zip     # Custom output name
+npx kustom-mc bundle --include-source   # Include .ts files
+```
+
+#### `kustom validate`
+
+Check scripts for errors.
+
+```bash
+npx kustom-mc validate           # Validate all scripts
+npx kustom-mc validate --strict  # Fail on warnings
+```
+
+#### `kustom new <type> <name>`
+
+Generate a new script from template.
+
+```bash
+npx kustom-mc new script my-script    # General script
+npx kustom-mc new block my-block      # Block definition
+npx kustom-mc new item my-item        # Item definition
+npx kustom-mc new gui my-gui          # GUI script
+```
+
+### In-Game Commands
+
+Register dynamic commands from scripts:
+
+```typescript
+run({ process, props, command }) {
+  // Register command
+  const cmdId = command.register("mycommand", () => {
+    console.log("Command executed!");
+    return "Success";
+  });
+  
+  // With arguments
+  const cmdId2 = command.registerWithArgs("greet", (sender, args) => {
+    const name = args[0] || "World";
+    process.getPlayer(sender).sendMessage("Hello, " + name + "!");
+  });
+  
+  // Give command to player
+  command.givePlayer(props.player, cmdId);
+  
+  // Remove access
+  command.removePlayer(props.player, cmdId);
+  
+  // Unregister
+  command.unregister(cmdId);
+}
+```
+
+---
+
+## Configuration
+
+### kustom.config.json
+
+```json
+{
+  "include": [
+    "scripts/**/*.ts",
+    "blocks/**/*.ts",
+    "items/**/*.ts"
+  ],
+  "exclude": [
+    "**/*.test.ts"
+  ],
+  "outDir": "dist",
+  "lib": ["scripts/lib"],
+  "deploy": {
+    "target": "../run/plugins/kustom-plugin/kustompack",
+    "reloadCommand": "/kustom reload"
+  },
+  "bundle": {
+    "output": "bundle/kustompack.zip",
+    "include": ["**/*.js", "textures/**/*", "gui/**/*", "models/**/*"]
+  }
+}
+```
+
+### Configuration Options
+
+| Option | Description |
+|--------|-------------|
+| `include` | Glob patterns for script files |
+| `exclude` | Patterns to exclude |
+| `outDir` | Output directory for compiled scripts |
+| `lib` | Directories containing shared libraries |
+| `deploy.target` | Server kustompack directory |
+| `deploy.reloadCommand` | Command to reload scripts |
+| `bundle.output` | Output path for bundle zip |
+| `bundle.include` | Files to include in bundle |
+
+---
+
+## Project Structure
+
+```
+my-kustom-pack/
+├── kustom.config.json
+├── tsconfig.json
+├── package.json
+├── scripts/
+│   ├── lib/           # Shared utilities
+│   │   └── utils.ts
+│   ├── main.ts        # Main scripts
+│   └── digicode.ts
+├── blocks/
+│   └── tower.ts       # Block definitions
+├── items/
+│   └── magic_wand.ts  # Item definitions
+├── gui/
+│   └── buttons/       # GUI textures
+├── textures/
+│   └── item/          # Item textures
+├── models/
+│   └── block/         # Block models
+└── dist/              # Compiled output
+    └── scripts/
+```
+
+---
+
+## License
+
+MIT