improve documentation

scripting/bedrocktool.d.ts

@@ -2,52 +2,284 @@ declare const console: {
     log(data: any);
 };
 
-declare type EventNames = "EntityAdd"|"EntityDataUpdate"|"ChunkAdd"|"BlockUpdate"|"SpawnParticle"
+
+/**
+ * Names of events that can be registered.
+ */
+declare type EventNames = 'EntityAdd' | 'EntityDataUpdate' | 'ChunkAdd' | 'BlockUpdate' | 'SpawnParticle';
+
+
+/**
+ * Callback for the `EntityAdd` event.
+ * 
+ * @param entity - The entity being added.
+ * @param metadata - Metadata associated with the entity.
+ * @param properties - Properties of the entity.
+ * @param time - The time the entity was added.
+ */
+declare type EntityAddCallback = (entity: Entity, metadata: EntityMetadata, properties: {[k: string]: EntityProperty}, time: number) => void;
+
+
+/**
+ * Callback for the `EntityDataUpdate` event.
+ * 
+ * @param entity - The entity being updated.
+ * @param metadata - Metadata associated with the entity.
+ * @param properties - Properties of the entity.
+ * @param time - The time the entity's data was updated.
+ */
+declare type EntityDataUpdateCallback = (entity: Entity, metadata: EntityMetadata, properties: {[k: string]: EntityProperty}, time: number) => void;
+
+
+/**
+ * Callback for the `ChunkAdd` event.
+ * 
+ * @param pos - The position of the chunk.
+ * @param time - The time the chunk was added.
+ */
+declare type ChunkAddCallback = (pos: [number, number, number], time: number) => void;
+
+
+/**
+ * Callback for the `BlockUpdate` event.
+ * 
+ * @param name - The name of the block.
+ * @param properties - Properties of the block.
+ * @param time - The time the block was updated.
+ */
+declare type BlockUpdateCallback = (name: string, properties: {[k: string]: any}, time: number) => void;
+
+
+/**
+ * Callback for the `SpawnParticle` event.
+ * 
+ * @param name - The name of the particle.
+ * @param x - The x-coordinate of the particle.
+ * @param y - The y-coordinate of the particle.
+ * @param z - The z-coordinate of the particle.
+ * @param time - The time the particle was spawned.
+ */
+declare type SpawnParticleCallback = (name: string, x: number, y: number, z: number, time: number) => void;
+
 
 declare const events: {
-    register(name: EventNames, callback: CallableFunction);
+    /**
+     * Registers a callback function to be executed when a specified event occurs.
+     * 
+     * @param name - The name of the event to register. Possible values are:
+     *   - 'EntityAdd': Triggered when a new entity is added.
+     *   - 'EntityDataUpdate': Triggered when an entity's data is updated.
+     *   - 'ChunkAdd': Triggered when a new chunk is added.
+     *   - 'BlockUpdate': Triggered when a block is updated.
+     *   - 'SpawnParticle': Triggered when a particle is spawned.
+     * 
+     * @param callback - The callback function to invoke when the event occurs. The parameters of the callback function vary based on the event:
+     *   - For 'EntityAdd':
+     *     - `entity` - The entity being added.
+     *     - `metadata` - Metadata associated with the entity.
+     *     - `properties` - Properties of the entity.
+     *     - `time` - The time the entity was added.
+     * 
+     * @example
+     * events.register('EntityAdd', (entity: Entity, metadata: EntityMetadata, properties, time) => {
+     *     console.log(`EntityAdd ${entity.EntityType}`);
+     * });
+     * 
+     */
+    register(name: 'EntityAdd', callback: EntityAddCallback): void;
+    /**
+     * Registers a callback function to be executed when a specified event occurs.
+     * 
+     * @param name - The name of the event to register. Possible values are:
+     *   - 'EntityAdd': Triggered when a new entity is added.
+     *   - 'EntityDataUpdate': Triggered when an entity's data is updated.
+     *   - 'ChunkAdd': Triggered when a new chunk is added.
+     *   - 'BlockUpdate': Triggered when a block is updated.
+     *   - 'SpawnParticle': Triggered when a particle is spawned.
+     * 
+     * @param callback - The callback function to invoke when the event occurs. The parameters of the callback function vary based on the event:
+     *   - For 'EntityDataUpdate':
+     *     - `entity` - The entity being updated.
+     *     - `metadata` - Metadata associated with the entity.
+     *     - `properties` - Properties of the entity.
+     *     - `time` - The time the entity's data was updated.
+     * 
+     * @example
+     * events.register('EntityDataUpdate', (entity, metadata, properties, time) => {
+     *     console.log(`EntityDataUpdate ${entity.EntityType}`);
+     * });
+     * 
+     */
+    register(name: 'EntityDataUpdate', callback: EntityDataUpdateCallback): void;
+    /**
+     * Registers a callback function to be executed when a specified event occurs.
+     * 
+     * @param name - The name of the event to register. Possible values are:
+     *   - 'EntityAdd': Triggered when a new entity is added.
+     *   - 'EntityDataUpdate': Triggered when an entity's data is updated.
+     *   - 'ChunkAdd': Triggered when a new chunk is added.
+     *   - 'BlockUpdate': Triggered when a block is updated.
+     *   - 'SpawnParticle': Triggered when a particle is spawned.
+     * 
+     * @param callback - The callback function to invoke when the event occurs. The parameters of the callback function vary based on the event:
+     *   - For 'ChunkAdd':
+     *     - `pos` - The position of the chunk.
+     *     - `time` - The time the chunk was added.
+     * 
+     * @example
+     * events.register('ChunkAdd', (pos, time) => {
+     *     console.log(`ChunkAdd ${pos}`);
+     * });
+     * 
+     */
+    register(name: 'ChunkAdd', callback: ChunkAddCallback): void;
+    /**
+     * Registers a callback function to be executed when a specified event occurs.
+     * 
+     * @param name - The name of the event to register. Possible values are:
+     *   - 'EntityAdd': Triggered when a new entity is added.
+     *   - 'EntityDataUpdate': Triggered when an entity's data is updated.
+     *   - 'ChunkAdd': Triggered when a new chunk is added.
+     *   - 'BlockUpdate': Triggered when a block is updated.
+     *   - 'SpawnParticle': Triggered when a particle is spawned.
+     * 
+     * @param callback - The callback function to invoke when the event occurs. The parameters of the callback function vary based on the event:
+     *   - For 'BlockUpdate':
+     *     - `name` - The name of the block.
+     *     - `properties` - Properties of the block.
+     *     - `time` - The time the block was updated.
+     * 
+     * @example
+     * events.register('BlockUpdate', (name, properties, time) => {
+     *     console.log(`BlockUpdate ${name}`);
+     * });
+     * 
+     */
+    register(name: 'BlockUpdate', callback: BlockUpdateCallback): void;
+    /**
+     * Registers a callback function to be executed when a specified event occurs.
+     * 
+     * @param name - The name of the event to register. Possible values are:
+     *   - 'EntityAdd': Triggered when a new entity is added.
+     *   - 'EntityDataUpdate': Triggered when an entity's data is updated.
+     *   - 'ChunkAdd': Triggered when a new chunk is added.
+     *   - 'BlockUpdate': Triggered when a block is updated.
+     *   - 'SpawnParticle': Triggered when a particle is spawned.
+     * 
+     * @param callback - The callback function to invoke when the event occurs. The parameters of the callback function vary based on the event:
+     *   - For 'SpawnParticle':
+     *     - `name` - The name of the particle.
+     *     - `x` - The x-coordinate of the particle.
+     *     - `y` - The y-coordinate of the particle.
+     *     - `z` - The z-coordinate of the particle.
+     *     - `time` - The time the particle was spawned.
+     * 
+     * @example
+     * events.register('SpawnParticle', (name, x, y, z, time) => {
+     *     console.log(`SpawnParticle ${name}`);
+     * });
+     * 
+     */
+    register(name: 'SpawnParticle', callback: SpawnParticleCallback): void;
 };
 
-declare type WindowID = number;
-declare type Slot = number;
 
+/**
+ * Represents an entity in the world.
+ */
 declare type Entity = {
+    /**
+     * The runtime identifier of the entity.
+     */
     RuntimeID: number
+    /**
+     * A unique identifier of the entity.
+     */
     UniqueID: number
+    /**
+     * The type identifier of the entity, e.g., 'minecraft:sheep'.
+     */
     EntityType: string
-
+    /**
+     * The current location of the entity, represented as an array containing x, y, and z coordinates.
+     */
     Position: [number, number, number];
+    /**
+     * The current pitch angle of the entity.
+     */
     Pitch: number;
+    /**
+     * The current yaw angle of the entity.
+     */
     Yaw: number;
+    /**
+     * The current velocity of the entity, represented as an array containing x, y, and z coordinates.
+     */
     Velocity: [number, number, number];
 }
 
+
+/**
+ * Represents an item instance in the game.
+ */
 declare type ItemInstance = {
+    /**
+     * The network identifier of the item.
+     */
     StackNetworkID: number;
+    /**
+     * The item stack associated with this instance.
+     */
     Stack: ItemStack;
 }
 
+
+/**
+ * Represents an item stack in the game.
+ */
 declare type ItemStack = {
+    /**
+     * The network identifier of the item.
+     */
     NetworkID: number;
+    /**
+     * The metadata value of the item.
+     */
     MetadataValue: number;
+    /**
+     * The runtime identifier of the block, if the item stack represents a block.
+     */
     BlockRuntimeID: number;
+    /**
+     * The quantity of items in the stack.
+     */
     Count: number;
+    /**
+     * The NBT data associated with the item stack.
+     */
     NBTData: {[k: string]: any};
+    /**
+     * A list of block identifiers that this item can be placed on.
+     */
     CanBePlacedOn: Array<string>;
+    /**
+     * A list of block identifiers that this item can break.
+     */
     CanBreak: Array<string>;
+    /**
+     * Indicates whether the item stack has a network identifier.
+     */
     HasNetworkID: boolean;
 }
 
-declare type ChunkPos = [number, number];
-
-
 
 declare type EntityMetadata = {
     [k: EntityDataKey]: any;
     SetFlag: (key: EntityDataKey, index: EntityDataFlag) => void;
     Flag: (key: EntityDataKey, index: EntityDataFlag) => boolean;
 };
 
+
 declare enum EntityDataKey {
 	Flags,
 	StructuralIntegrity,
@@ -182,6 +414,7 @@ declare enum EntityDataKey {
 	CollisionBox,
 };
 
+
 declare enum EntityDataFlag {
     OnFire,
 	Sneaking,
@@ -298,4 +531,4 @@ declare enum EntityDataFlag {
 	FeelingHappy,
 	Searching,
 	Crawling,
-}
+}

scripting/example.js

@@ -1,22 +1,23 @@
-events.register("EntityAdd", (entity, metadata, properties, time) => {
-    console.log("EntityAdd "+ entity.EntityType);
-})
+events.register('EntityAdd', (entity, metadata, properties, time) => {
+    console.log(`EntityAdd ${entity.EntityType}`);
+});
 
-events.register("EntityDataUpdate", (entity, metadata, properties, time) => {
-    console.log("EntityDataUpdate "+ entity.EntityType);
-})
 
-events.register("ChunkAdd", (pos, time) => {
-    console.log("ChunkAdd "+ pos);
-})
+events.register('EntityDataUpdate', (entity, metadata, properties, time) => {
+    console.log(`EntityDataUpdate ${entity.EntityType}`);
+});
 
-events.register("BlockUpdate", (name, properties, time) => {
-    console.log("BlockUpdate "+ name);
-})
 
-events.register("SpawnParticle", (name, x,y,z, time) => {
-    console.log("SpawnParticle "+ name);
-})
+events.register('ChunkAdd', (pos, time) => {
+    console.log(`ChunkAdd ${pos}`);
+});
 
 
+events.register('BlockUpdate', (name, properties, time) => {
+    console.log(`BlockUpdate ${name}`);
+});
 
+
+events.register('SpawnParticle', (name, x, y, z, time) => {
+    console.log(`SpawnParticle ${name}`);
+});

scripting/scripting-ts/example.ts

@@ -1,16 +1,23 @@
+events.register('EntityAdd', (entity, metadata, properties, time) => {
+    console.log(`EntityAdd ${entity.EntityType}`);
+});
 
-function OnEntityAdd(entity: Entity, data: EntityMetadata): boolean {
-    console.log("adding entity " + entity.EntityType);
-    console.log(`NoAI: ${data.Flag(EntityDataKey.Flags, EntityDataFlag.NoAI)}`)
-    console.log(`entity name: ${data[EntityDataKey.Name]}`)
-    return false;
-}
-
-function OnChunkAdd(pos: ChunkPos): boolean {
-    return false;
-}
-
-function OnEntityDataUpdate(entity: Entity, data: EntityMetadata) {
-    console.log("OnEntityDataUpdate");
-    console.log("entity name: "+data[EntityDataKey.Name]);
-}
+
+events.register('EntityDataUpdate', (entity, metadata, properties, time) => {
+    console.log(`EntityDataUpdate ${entity.EntityType}`);
+});
+
+
+events.register('ChunkAdd', (pos, time) => {
+    console.log(`ChunkAdd ${pos}`);
+});
+
+
+events.register('BlockUpdate', (name, properties, time) => {
+    console.log(`BlockUpdate ${name}`);
+});
+
+
+events.register('SpawnParticle', (name, x, y, z, time) => {
+    console.log(`SpawnParticle ${name}`);
+});