From 8319b28641a304c742f1703d399eb8521199a99e Mon Sep 17 00:00:00 2001 From: p12h4 Date: Wed, 24 Jul 2024 21:50:57 +0200 Subject: [PATCH] improve documentation --- scripting/bedrocktool.d.ts | 251 ++++++++++++++++++++++++++++-- scripting/example.js | 31 ++-- scripting/scripting-ts/example.ts | 37 +++-- 3 files changed, 280 insertions(+), 39 deletions(-) diff --git a/scripting/bedrocktool.d.ts b/scripting/bedrocktool.d.ts index 27cff88..9fd0594 100644 --- a/scripting/bedrocktool.d.ts +++ b/scripting/bedrocktool.d.ts @@ -2,45 +2,276 @@ 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; + /** + * A list of block identifiers that this item can break. + */ CanBreak: Array; + /** + * Indicates whether the item stack has a network identifier. + */ HasNetworkID: boolean; } -declare type ChunkPos = [number, number]; - - declare type EntityMetadata = { [k: EntityDataKey]: any; @@ -48,6 +279,7 @@ declare type EntityMetadata = { 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, -} +} \ No newline at end of file diff --git a/scripting/example.js b/scripting/example.js index 08bd842..c65453e 100644 --- a/scripting/example.js +++ b/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}`); +}); \ No newline at end of file diff --git a/scripting/scripting-ts/example.ts b/scripting/scripting-ts/example.ts index 9b7294a..c65453e 100644 --- a/scripting/scripting-ts/example.ts +++ b/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}`); +}); \ No newline at end of file