kustom-mc 0.1.3 → 0.1.4

package/dist/commands/init.js

@@ -26,11 +26,9 @@ export const initCommand = new Command('init')
             process.exit(1);
         }
     }
-    // Create directory structure
+    // Create directory structure (all scripts go in scripts/, type determined by __type)
     const dirs = [
         'scripts/lib',
-        'blocks',
-        'items',
         'textures',
         'gui',
         'models',
@@ -68,8 +66,6 @@ export const initCommand = new Command('init')
         },
         include: [
             "scripts/**/*.ts",
-            "blocks/**/*.ts",
-            "items/**/*.ts",
             "dist/types/**/*.d.ts",
             ".kustom/types/**/*.d.ts",
             "node_modules/kustom-mc/dist/types/globals.d.ts"
@@ -80,9 +76,7 @@ export const initCommand = new Command('init')
     // Write kustom.config.json with manifest
     const kustomConfig = {
         include: [
-            "scripts/**/*.ts",
-            "blocks/**/*.ts",
-            "items/**/*.ts"
+            "scripts/**/*.ts"
         ],
         exclude: [
             "**/*.test.ts",
@@ -189,11 +183,9 @@ dist/
   ├── kustom.config.json   # Pack configuration & manifest
   ├── tsconfig.json        # TypeScript configuration
   ├── package.json         # npm configuration
-  ├── scripts/             # General scripts
+   ├── scripts/             # All scripts (type determined by defineScript/defineBlock/defineItem)
   │   ├── example.ts       # Example script
   │   └── lib/             # Shared utilities
-  ├── blocks/              # Block definitions
-  ├── items/               # Item definitions
   ├── textures/            # Texture files
   ├── models/              # Model files
   ├── sounds/              # Sound files

package/dist/commands/login.js

@@ -1,6 +1,7 @@
 import { Command } from 'commander';
+import * as readline from 'readline';
 import chalk from 'chalk';
-import { loadConfig } from '../config.js';
+import { loadConfig, saveConfigServerUrl } from '../config.js';
 import { saveServerToken, getServerCredential, normalizeServerUrl, listStoredServers, removeServerCredential } from '../credentials.js';
 /**
  * Validate a token with the server.
@@ -60,6 +61,7 @@ export const loginCommand = new Command('login')
     // Determine server URL
     let serverUrl;
     let token;
+    let serverUrlExplicit = false; // true when user provided the URL as a CLI argument
     // If only one argument provided, it might be the token (use config for server)
     if (serverUrlArg && !tokenArg && !serverUrlArg.includes('://') && !serverUrlArg.includes(':')) {
         // Looks like a token, not a URL
@@ -76,6 +78,7 @@ export const loginCommand = new Command('login')
     else if (serverUrlArg) {
         serverUrl = serverUrlArg;
         token = tokenArg;
+        serverUrlExplicit = true;
     }
     else {
         // No arguments - use config
@@ -159,6 +162,29 @@ export const loginCommand = new Command('login')
             console.log(`  Token expires: ${result.expiresAt}`);
         }
         console.log(`\nCredentials saved to ~/.kustom/credentials.json`);
+        // Offer to update kustom.config.json if the user explicitly provided a server URL
+        if (serverUrlExplicit) {
+            const config = loadConfig(process.cwd());
+            const configServerUrl = config.server?.url ? normalizeServerUrl(config.server.url) : undefined;
+            if (configServerUrl !== serverUrl) {
+                const rl = readline.createInterface({
+                    input: process.stdin,
+                    output: process.stdout
+                });
+                const answer = await new Promise((resolve) => {
+                    rl.question(chalk.yellow(`Update server.url in kustom.config.json to ${serverUrl}? [y/N] `), resolve);
+                });
+                rl.close();
+                if (answer.toLowerCase() === 'y' || answer.toLowerCase() === 'yes') {
+                    if (saveConfigServerUrl(process.cwd(), serverUrl)) {
+                        console.log(chalk.green('Updated server.url in kustom.config.json'));
+                    }
+                    else {
+                        console.log(chalk.yellow('Could not update kustom.config.json (file not found or not writable)'));
+                    }
+                }
+            }
+        }
     }
     catch (error) {
         console.error(chalk.red(`Login failed: ${error instanceof Error ? error.message : error}`));

package/dist/commands/new.js

@@ -22,32 +22,37 @@ export default defineScript({
   }
 });
 `,
-    block: `import { defineScript } from 'kustom-mc';
+    block: `import { defineBlock } from 'kustom-mc';
 
-export default defineScript({
-  run({ shaper }) {
-    shaper.create("{{name}}")
-      .withModel("kustom:block/{{name}}")
-      .fullBlockCollision()
-      .onClick((event) => {
-        const player = event.player;
-        player.sendMessage("You clicked {{name}}!");
-      })
-      .register();
+export default defineBlock({
+  id: "{{name}}",
+  model: "kustom:block/{{name}}",
+  collision: "full",
+  autoPlace: true,
+
+  onClick(event) {
+    event.player.sendMessage("You clicked {{name}}!");
+  },
+
+  onBreak(event) {
+    event.player.sendMessage("{{name}} broken!");
+  },
+
+  onPlace(event) {
+    event.player.sendMessage("{{name}} placed!");
   }
 });
 `,
-    item: `import { defineScript } from 'kustom-mc';
+    item: `import { defineItem } from 'kustom-mc';
 
-export default defineScript({
-  run({ items, definition }) {
-    items.create("{{name}}")
-      .withModel(definition.model("kustom:item/{{name}}"))
-      .on("rightClick", (event) => {
-        const player = event.player;
-        player.sendMessage("You used {{name}}!");
-      })
-      .register();
+export default defineItem({
+  id: "{{name}}",
+  material: "PAPER",
+  model: "kustom:item/{{name}}",
+  displayName: "{{name}}",
+
+  onRightClick(event) {
+    event.player.sendMessage("You used {{name}}!");
   }
 });
 `,
@@ -94,10 +99,11 @@ export const newCommand = new Command('new')
         process.exit(1);
     }
     // Determine output directory and file
+    // All script types go in scripts/ — type is determined by defineScript/defineBlock/defineItem
     const dirMap = {
         script: 'scripts',
-        block: 'blocks',
-        item: 'items',
+        block: 'scripts',
+        item: 'scripts',
         gui: 'scripts'
     };
     const dir = dirMap[type];

package/dist/commands/validate.js

@@ -30,7 +30,7 @@ export const validateCommand = new Command('validate')
     }
     console.log('Validating scripts...');
     // Find all TypeScript files
-    const patterns = config.include || ['scripts/**/*.ts', 'blocks/**/*.ts', 'items/**/*.ts'];
+    const patterns = config.include || ['scripts/**/*.ts'];
     const excludePatterns = config.exclude || [];
     const files = [];
     for (const pattern of patterns) {

package/dist/config.d.ts

@@ -80,3 +80,9 @@ export declare function parseCrossPackImport(importPath: string): {
  * Create a fully qualified namespaced ID.
  */
 export declare function createNamespacedId(packId: string, type: string, name: string): string;
+/**
+ * Update the server.url in kustom.config.json.
+ * Preserves all other config properties.
+ * Returns true if the file was updated, false if no config file exists.
+ */
+export declare function saveConfigServerUrl(cwd: string, serverUrl: string): boolean;

package/dist/config.js

@@ -1,7 +1,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 const defaultConfig = {
-    include: ['scripts/**/*.ts', 'blocks/**/*.ts', 'items/**/*.ts'],
+    include: ['scripts/**/*.ts'],
     exclude: ['**/*.test.ts', '**/*.spec.ts'],
     outDir: 'dist',
     lib: ['scripts/lib'],
@@ -159,3 +159,27 @@ export function parseCrossPackImport(importPath) {
 export function createNamespacedId(packId, type, name) {
     return `${packId}:${type}/${name}`;
 }
+/**
+ * Update the server.url in kustom.config.json.
+ * Preserves all other config properties.
+ * Returns true if the file was updated, false if no config file exists.
+ */
+export function saveConfigServerUrl(cwd, serverUrl) {
+    const configPath = path.join(cwd, 'kustom.config.json');
+    if (!fs.existsSync(configPath)) {
+        return false;
+    }
+    try {
+        const content = fs.readFileSync(configPath, 'utf-8');
+        const config = JSON.parse(content);
+        if (!config.server || typeof config.server !== 'object') {
+            config.server = {};
+        }
+        config.server.url = serverUrl;
+        fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/runtime.d.ts

@@ -8,7 +8,7 @@
  * plain objects with __type property injected.
  */
 import './types/globals.js';
-import type { ScriptConfig, ExportedScript, PropSchema, EventSchema, EmptyEventSchema, BlockConfig, BlockDefinition, ItemConfig, ItemDefinition, ScreenConstructor, ContainerConstructor, ElementFactory, ScriptableLocationFactory, PropsAPI, CellStateUtils } from './types/index.js';
+import type { ScriptConfig, ScriptConfigWithMethods, ExportedScript, PropSchema, EventSchema, EmptyEventSchema, BlockConfig, BlockDefinition, ItemConfig, ItemDefinition, ScreenConstructor, ContainerConstructor, ElementFactory, ScriptableLocationFactory, PropsAPI, CellStateUtils, MethodMap } from './types/index.js';
 /**
  * Screen constructor - create new screens for GUIs.
  * Actual value is injected by Java at runtime.
@@ -59,13 +59,31 @@ export declare const ScriptableLocation: ScriptableLocationFactory;
  *     onSuccess: Props.Boolean(),
  *     onError: Props.String(),
  *   },
- *   run({ process, props }) {
+ *   methods: {
+ *     greet({ executor, props }) {
+ *       executor.asPlayer()?.sendMessage(props.message);
+ *     },
+ *   },
+ *   run({ process, props, methods }) {
  *     const player = process.getPlayer(props.player);
  *     player.sendMessage(props.message);
+ *     methods.greet();  // ctx auto-injected!
  *     process.emit("onSuccess", true);  // Typed!
  *   }
  * });
  */
+/**
+ * Define a kustom script with type safety and strongly-typed methods.
+ *
+ * Overload 1: Script WITH methods — M is inferred from the methods object,
+ * providing full autocomplete and type safety for ctx.methods.
+ */
+export declare function defineScript<P extends PropSchema, E extends EventSchema, M extends MethodMap<P, E>>(config: ScriptConfigWithMethods<P, E, M>): ExportedScript<P, E>;
+/**
+ * Define a kustom script with type safety.
+ *
+ * Overload 2: Script WITHOUT methods — simpler signature, backward compatible.
+ */
 export declare function defineScript<P extends PropSchema = Record<string, never>, E extends EventSchema = EmptyEventSchema>(config: ScriptConfig<P, E>): ExportedScript<P, E>;
 /**
  * Define a custom block with type safety.
@@ -113,4 +131,4 @@ export declare function defineBlock(config: BlockConfig): BlockDefinition;
  * });
  */
 export declare function defineItem(config: ItemConfig): ItemDefinition;
-export type { ScriptConfig, ScriptDefinition, ExportedScript, ScriptContext, PropSchema, PropAPI, InferProps, PropsAPI, EventSchema, EmptyEventSchema, InferEventPayload, ScriptModule, ScriptProcess, TypedScriptProcess, InferScriptModule, McModuleAPI, TypedMcModuleAPI, ProcessExecutorAPI, CameraAPI, SessionAPI, ChatGUIAPI, CommandManager, BetterModelEntityAPI, ShaperAPI, ItemAPI, DefinitionBuilder, ScriptablePlayer, BlockConfig, BlockDefinition, BlockClickEvent, BlockBreakEvent, BlockPlaceEvent, ItemConfig, ItemDefinition, ScreenConstructor, ContainerConstructor, ElementFactory, ScriptableLocationFactory, CellStateUtils, } from './types/index.js';
+export type { ScriptConfig, ScriptDefinition, ExportedScript, BaseScriptContext, ScriptContext, PropSchema, PropAPI, InferProps, PropsAPI, WrappedMethods, MethodMap, EventSchema, EmptyEventSchema, InferEventPayload, ScriptModule, ScriptProcess, TypedScriptProcess, InferScriptModule, McModuleAPI, TypedMcModuleAPI, ProcessExecutorAPI, CameraAPI, SessionAPI, ChatGUIAPI, CommandManager, BetterModelEntityAPI, ShaperAPI, ItemAPI, DefinitionBuilder, ScriptablePlayer, BlockConfig, BlockDefinition, BlockClickEvent, BlockBreakEvent, BlockPlaceEvent, ItemConfig, ItemDefinition, ScreenConstructor, ContainerConstructor, ElementFactory, ScriptableLocationFactory, CellStateUtils, } from './types/index.js';

package/dist/runtime.js

@@ -9,36 +9,11 @@
  */
 // Import globals for side effects - makes console, setTimeout, etc. available
 import './types/globals.js';
-/**
- * Define a kustom script with type safety.
- *
- * This is a type-only helper that returns its input unchanged.
- * The Java ProcessManager extracts the `run` function and calls it
- * with the ScriptContext.
- *
- * @example
- * import { defineScript, Props } from 'kustom-mc';
- *
- * export default defineScript({
- *   props: {
- *     player: Props.String(),
- *     message: Props.String("Hello!"),
- *   },
- *   events: {
- *     onSuccess: Props.Boolean(),
- *     onError: Props.String(),
- *   },
- *   run({ process, props }) {
- *     const player = process.getPlayer(props.player);
- *     player.sendMessage(props.message);
- *     process.emit("onSuccess", true);  // Typed!
- *   }
- * });
- */
+// Implementation
 export function defineScript(config) {
     // Simply return the config - the Java side will handle execution
     // The return type is ExportedScript which combines:
-    // - Definition metadata (props, events, __type) for the Java runtime
+    // - Definition metadata (props, events, methods, __type) for the Java runtime
     // - ScriptModule interface with .run(props) method for TypeScript imports
     return config;
 }

package/dist/types/__tests__/debug-inference.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Debug: Check what M resolves to
+ */
+export {};

package/dist/types/__tests__/debug-inference.js

@@ -0,0 +1,25 @@
+/**
+ * Debug: Check what M resolves to
+ */
+import { defineScript } from '../../runtime.js';
+const Props = {
+    String: (defaultValue) => ({ __brand: 'StringPropAPI', defaultValue }),
+};
+const result = defineScript({
+    props: {
+        message: Props.String("Hello!"),
+    },
+    methods: {
+        toto({ executor }) {
+            executor.asPlayer()?.sendMessage("toto!");
+        },
+    },
+    run({ methods }) {
+        // Let's see what type methods is
+        const m = methods;
+        const _check = m;
+        console.log(_check);
+    },
+});
+const _r = result;
+console.log(_r);

package/dist/types/__tests__/defineScript-methods-dx-test.d.ts

@@ -0,0 +1,27 @@
+/**
+ * DX test for strongly-typed defineScript methods.
+ *
+ * This simulates the EXACT user experience — calling defineScript()
+ * with methods and verifying autocomplete/type safety.
+ *
+ * Run: npx tsc --noEmit
+ * If this file compiles, the DX is correct.
+ */
+declare const _default: import("../index.js").ExportedScript<{
+    message: {
+        __brand: "StringPropAPI";
+        defaultValue: string | undefined;
+    };
+    count: {
+        __brand: "NumberPropAPI";
+        defaultValue: number | undefined;
+    };
+}, import("../index.js").EventSchema>;
+export default _default;
+export declare const noMethodsScript: import("../index.js").ExportedScript<{
+    name: {
+        __brand: "StringPropAPI";
+        defaultValue: string | undefined;
+    };
+}, import("../index.js").EmptyEventSchema>;
+export declare const bareScript: import("../index.js").ExportedScript<Record<string, never>, import("../index.js").EmptyEventSchema>;

package/dist/types/__tests__/defineScript-methods-dx-test.js

@@ -0,0 +1,76 @@
+/**
+ * DX test for strongly-typed defineScript methods.
+ *
+ * This simulates the EXACT user experience — calling defineScript()
+ * with methods and verifying autocomplete/type safety.
+ *
+ * Run: npx tsc --noEmit
+ * If this file compiles, the DX is correct.
+ */
+import { defineScript } from '../../runtime.js';
+// Simulate Props (these are runtime-injected, so we cast)
+const Props = {
+    String: (defaultValue) => ({ __brand: 'StringPropAPI', defaultValue }),
+    Number: (defaultValue) => ({ __brand: 'NumberPropAPI', defaultValue }),
+    Boolean: (defaultValue) => ({ __brand: 'BooleanPropAPI', defaultValue }),
+};
+// ============================================
+// Test: Full DX with methods
+// ============================================
+export default defineScript({
+    props: {
+        message: Props.String("Hello!"),
+        count: Props.Number(5),
+    },
+    methods: {
+        toto({ executor }) {
+            // ✅ executor is typed as ProcessExecutorAPI
+            executor.asPlayer()?.sendMessage("toto!");
+        },
+        greet({ executor, props }) {
+            // ✅ props is typed: props.message is string, props.count is number
+            const _msg = props.message;
+            const _cnt = props.count;
+            // Note: methods receive BaseScriptContext (no `methods` field)
+            // to avoid circular generic inference. Only run() gets methods.
+            executor.asPlayer()?.sendMessage("greet!");
+        },
+        doSomething({ executor }) {
+            // ✅ Methods receive BaseScriptContext with all subsystems
+            executor.asPlayer()?.sendMessage("doSomething!");
+        },
+    },
+    run({ executor, props, methods }) {
+        // ✅ props is typed
+        const _msg = props.message;
+        const _cnt = props.count;
+        // ✅ methods are typed with autocomplete
+        methods.toto();
+        methods.greet();
+        methods.doSomething();
+        // ✅ executor is typed
+        executor.asPlayer()?.sendMessage(props.message);
+    },
+});
+// ============================================
+// Test: Script without methods (backward compat)
+// ============================================
+export const noMethodsScript = defineScript({
+    props: {
+        name: Props.String("World"),
+    },
+    run({ props }) {
+        // ✅ props is typed
+        const _name = props.name;
+        console.log(_name);
+    },
+});
+// ============================================
+// Test: Script with no props and no methods
+// ============================================
+export const bareScript = defineScript({
+    run() {
+        // ✅ Compiles fine with no props/methods
+        console.log("bare script");
+    },
+});

package/dist/types/__tests__/defineScript-methods-negative-test.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Negative type test for strongly-typed defineScript methods.
+ *
+ * Uses @ts-expect-error to verify that invalid method calls
+ * produce type errors. If a @ts-expect-error line does NOT
+ * produce an error, tsc will report "Unused '@ts-expect-error' directive".
+ *
+ * Run: npx tsc --noEmit
+ */
+declare const _default: import("../index.js").ExportedScript<{
+    message: {
+        __brand: "StringPropAPI";
+        defaultValue: string | undefined;
+    };
+}, import("../index.js").EventSchema>;
+export default _default;

package/dist/types/__tests__/defineScript-methods-negative-test.js

@@ -0,0 +1,36 @@
+/**
+ * Negative type test for strongly-typed defineScript methods.
+ *
+ * Uses @ts-expect-error to verify that invalid method calls
+ * produce type errors. If a @ts-expect-error line does NOT
+ * produce an error, tsc will report "Unused '@ts-expect-error' directive".
+ *
+ * Run: npx tsc --noEmit
+ */
+import { defineScript } from '../../runtime.js';
+const Props = {
+    String: (defaultValue) => ({ __brand: 'StringPropAPI', defaultValue }),
+};
+export default defineScript({
+    props: {
+        message: Props.String("Hello!"),
+    },
+    methods: {
+        toto({ executor }) {
+            executor.asPlayer()?.sendMessage("toto!");
+        },
+        greet({ executor }) {
+            // Methods receive BaseScriptContext — no `methods` field.
+            // This avoids circular generic inference.
+            executor.asPlayer()?.sendMessage("greet!");
+        },
+    },
+    run({ methods }) {
+        methods.toto(); // ✅ valid
+        methods.greet(); // ✅ valid
+        // @ts-expect-error — 'nope' does not exist on methods
+        methods.nope();
+        // @ts-expect-error — 'doesNotExist' does not exist on methods
+        methods.doesNotExist();
+    },
+});

package/dist/types/__tests__/methods-type-test.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Type-level test for strongly-typed defineScript methods.
+ *
+ * This file is NOT executed — it only verifies that TypeScript
+ * correctly infers method types and provides autocomplete.
+ *
+ * Run: npx tsc --noEmit
+ * If this file compiles, the types are correct.
+ */
+export {};

package/dist/types/__tests__/methods-type-test.js

@@ -0,0 +1,39 @@
+/**
+ * Type-level test for strongly-typed defineScript methods.
+ *
+ * This file is NOT executed — it only verifies that TypeScript
+ * correctly infers method types and provides autocomplete.
+ *
+ * Run: npx tsc --noEmit
+ * If this file compiles, the types are correct.
+ */
+// These should be the stripped signatures:
+const _test1 = {
+    greet: (name) => name, // ctx stripped, (name: string) => string
+    wave: () => { }, // ctx stripped, () => void
+};
+// Verify the config type accepts methods and that ctx.methods inside run() is strongly typed.
+const _config = {
+    props: undefined,
+    methods: {
+        toto(ctx) {
+            ctx.executor.asPlayer()?.sendMessage("toto!");
+        },
+        greet(ctx) {
+            // Methods receive BaseScriptContext — no `methods` field
+            ctx.executor.asPlayer()?.sendMessage("greet!");
+        },
+    },
+    run(ctx) {
+        ctx.methods.toto();
+        ctx.methods.greet();
+        // ctx.props should be typed
+        const _msg = ctx.props.message;
+        const _cnt = ctx.props.count;
+    },
+};
+const _emptyCtx = {};
+// Should be Record<string, never> — no methods
+const _emptyWrapped = {};
+console.log("Type tests passed (compile-time only)", _test1, _config, _emptyCtx, _emptyWrapped);
+export {};

package/dist/types/index.d.ts

@@ -97,6 +97,22 @@ export type EmptyEventSchema = Record<string, never>;
  * Infer the event payload type from an EventSchema.
  */
 export type InferEventPayload<E extends EventSchema, K extends keyof E> = InferPropType<E[K]>;
+/**
+ * Strips the first ctx parameter from each method, producing the type
+ * available as ctx.methods inside scripts.
+ *
+ * Given methods like `{ greet(ctx: ScriptContext, ...args): void }`,
+ * produces `{ greet(...args): void }` — ctx is auto-injected at runtime.
+ */
+export type WrappedMethods<M> = {
+    [K in keyof M]: M[K] extends (ctx: never, ...args: infer A) => infer R ? (...args: A) => R : () => unknown;
+};
+/**
+ * Script configuration for defineScript() — without methods.
+ *
+ * @typeParam P - Props schema type
+ * @typeParam E - Events schema type
+ */
 export interface ScriptConfig<P extends PropSchema, E extends EventSchema = EmptyEventSchema> {
     /** Props schema with types and defaults */
     props?: P;
@@ -124,6 +140,47 @@ export interface ScriptConfig<P extends PropSchema, E extends EventSchema = Empt
      */
     run: (this: TypedMcModuleAPI<E>, ctx: ScriptContext<InferProps<P>, E>) => void;
 }
+/**
+ * Script configuration for defineScript() — with strongly-typed methods.
+ *
+ * Uses a generic `M` to capture the literal shape of the methods object.
+ * Each method receives a `ScriptContext` with `WrappedMethods<M>` providing
+ * full autocomplete for `ctx.methods.*`.
+ *
+ * The `methods` field uses a mapped type over `keyof M` so TypeScript
+ * can infer `M` from the object literal keys, then constrains each
+ * method's signature.
+ *
+ * @typeParam P - Props schema type
+ * @typeParam E - Events schema type
+ * @typeParam M - Methods record type (inferred from the methods object literal)
+ */
+/** Constraint for the methods record — each method receives BaseScriptContext */
+export type MethodMap<P extends PropSchema, E extends EventSchema> = Record<string, (ctx: BaseScriptContext<InferProps<P>, E>, ...args: unknown[]) => unknown>;
+export type ScriptConfigWithMethods<P extends PropSchema, E extends EventSchema, M extends MethodMap<P, E>> = {
+    props?: P;
+    events?: E;
+    /**
+     * Named methods that can be called externally via `process.call("methodName", ...args)`
+     * or internally via `ctx.methods.methodName()`.
+     *
+     * Each method receives `(ctx: BaseScriptContext, ...extraArgs)` — a context without `methods`
+     * to avoid circular generic inference. At runtime, Java injects the full context.
+     *
+     * When called via `ctx.methods` in `run()`, the `ctx` parameter is auto-injected.
+     *
+     * @example
+     * ```typescript
+     * methods: {
+     *   greet({ executor }) {
+     *     executor.asPlayer()?.sendMessage("Hello!");
+     *   },
+     * }
+     * ```
+     */
+    methods: M;
+    run: (this: TypedMcModuleAPI<E>, ctx: ScriptContext<InferProps<P>, E, WrappedMethods<M>>) => void;
+};
 export interface ScriptDefinition<P extends PropSchema, E extends EventSchema = EmptyEventSchema> {
     props?: P;
     events?: E;
@@ -260,10 +317,14 @@ export interface ItemDefinition extends ItemConfig {
     readonly __type: "item";
 }
 /**
- * Context passed to script run function.
- * Contains all APIs and subsystems available to scripts.
+ * Base context passed to method functions.
+ * Same as ScriptContext but without `methods` to avoid circular generic inference.
+ * At runtime, Java actually injects the full context including methods.
+ *
+ * @typeParam P - Inferred props type
+ * @typeParam E - Event schema type
  */
-export interface ScriptContext<P = Record<string, unknown>, E extends EventSchema = EmptyEventSchema> {
+export interface BaseScriptContext<P = Record<string, unknown>, E extends EventSchema = EmptyEventSchema> {
     /** Process API for script management (typed for events if declared) */
     process: TypedMcModuleAPI<E>;
     /** Validated props */
@@ -289,6 +350,33 @@ export interface ScriptContext<P = Record<string, unknown>, E extends EventSchem
     /** Persistent storage system */
     storage: StorageAPI;
 }
+/**
+ * Full context passed to the script `run()` function.
+ * Extends BaseScriptContext with strongly-typed `methods`.
+ *
+ * @typeParam P - Inferred props type
+ * @typeParam E - Event schema type
+ * @typeParam Methods - Strongly-typed methods map (auto-inferred from defineScript)
+ */
+export interface ScriptContext<P = Record<string, unknown>, E extends EventSchema = EmptyEventSchema, Methods = Record<string, never>> extends BaseScriptContext<P, E> {
+    /**
+     * Callable methods defined in defineScript({ methods: { ... } }).
+     * These are wrapped so `ctx` is auto-injected — call them directly without passing ctx.
+     *
+     * Fully typed: autocomplete shows only the methods you defined,
+     * and calling a non-existent method is a type error.
+     *
+     * @example
+     * ```typescript
+     * run({ methods }) {
+     *   methods.greet();        // ✅ ctx is auto-injected, autocomplete works
+     *   methods.farewell("arg"); // ✅ extra args passed through
+     *   methods.nope();          // ❌ type error — not defined
+     * }
+     * ```
+     */
+    methods: Methods;
+}
 export interface PropSchema {
     [key: string]: PropAPI;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kustom-mc",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "CLI and type library for kustompack development",
   "type": "module",
   "main": "dist/runtime.js",