finish basic access control system

types/advanced-peripherals/block-reader.d.ts

@@ -0,0 +1,38 @@
+/// <reference path="./shared.d.ts" />
+
+/**
+ * Represents the Block Reader peripheral from Advanced Peripherals.
+ * Used to read data about blocks in front of it.
+ *
+ * @see https://docs.advanced-peripherals.de/0.7/peripherals/block_reader/
+ */
+/** @noSelf **/
+declare interface BlockReaderPeripheral extends IPeripheral {
+  /**
+   * Returns the registry name of the block (ex. minecraft:dirt).
+   *
+   * @returns The registry name of the block
+   */
+  getBlockName(): string;
+
+  /**
+   * Returns the block data of the block if block is a tile entity.
+   *
+   * @returns The block data table if the block is a tile entity, otherwise nil
+   */
+  getBlockData(): BlockDetailData | undefined;
+
+  /**
+   * Returns the properties of a block and its state.
+   *
+   * @returns The block states table if available, otherwise nil
+   */
+  getBlockStates(): Record<string, unknown> | undefined;
+
+  /**
+   * Returns true whether the block is a tile entity or not.
+   *
+   * @returns Boolean indicating if the block is a tile entity, or nil if unable to determine
+   */
+  isTileEntity(): boolean | undefined;
+}

types/advanced-peripherals/chat-box.d.ts

@@ -0,0 +1,150 @@
+/// <reference path="./shared.d.ts" />
+
+/**
+ * Represents the Chat Box peripheral from Advanced Peripherals.
+ * Used to interact with Minecraft's chat system.
+ *
+ * @see https://minecraft.wiki/w/Text_component_format
+ * @see https://docs.advanced-peripherals.de/latest/peripherals/chat_box/
+ */
+/** @noSelf **/
+declare interface ChatBoxPeripheral extends IPeripheral {
+  /**
+   * Broadcasts a message to the global chat or if range is specified it is sent to all players in the range.
+   * The prefix will change the text that appears inside the brackets at the start of a message. Defaults to "AP".
+   * To change the brackets used around the prefix you must specify a string like so: "[]", "()", "<>", ...
+   * bracketColor specifies the color to use for the brackets, this must be in the MOTD code format.
+   * If utf8Support is true: message, prefix, brackets, and bracketColor are all expected to be UTF8 encoded, using the utf8 standard library, unicode escape sequences, or similar.
+   *
+   * @param message The message to send
+   * @param prefix The prefix to display in brackets at the start of the message (defaults to "AP")
+   * @param brackets The bracket style around the prefix (e.g., "[]", "()", "<>")
+   * @param bracketColor The color for the brackets in MOTD code format
+   * @param range The range in blocks to send the message to players (if not global)
+   * @param utf8Support Whether to use UTF8 encoding for the message
+   * @returns true if the message is successfully sent, or nil and an error message if it fails
+   */
+  sendMessage(
+    message: string,
+    prefix?: string,
+    brackets?: string,
+    bracketColor?: string,
+    range?: number,
+    utf8Support?: boolean,
+  ): LuaMultiReturn<[boolean, string | undefined]>;
+
+  /**
+   * Similar to sendMessage() this sends a message to one specific player. Specify the player to send the message to with the username parameter.
+   *
+   * @param message The message to send
+   * @param username The username of the player to send the message to
+   * @param prefix The prefix to display in brackets at the start of the message (defaults to "AP")
+   * @param brackets The bracket style around the prefix (e.g., "[]", "()", "<>")
+   * @param bracketColor The color for the brackets in MOTD code format
+   * @param range The range in blocks to send the message to players (if not global)
+   * @param utf8Support Whether to use UTF8 encoding for the message
+   * @returns true if the message is successfully sent, or nil and an error message if it fails
+   */
+  sendMessageToPlayer(
+    message: string,
+    username: string,
+    prefix?: string,
+    brackets?: string,
+    bracketColor?: string,
+    range?: number,
+    utf8Support?: boolean,
+  ): LuaMultiReturn<[boolean, string | undefined]>;
+
+  /**
+   * Sends a toast to the specified player. The design of the toast is the classic notification design.
+   * It's planned to add a custom rendered design in the future.
+   *
+   * @param message The message for the toast
+   * @param title The title of the toast
+   * @param username The username of the player to send the toast to
+   * @param prefix The prefix to display in brackets at the start of the message (defaults to "AP")
+   * @param brackets The bracket style around the prefix (e.g., "[]", "()", "<>")
+   * @param bracketColor The color for the brackets in MOTD code format
+   * @param range The range in blocks to send the message to players (if not global)
+   * @param utf8Support Whether to use UTF8 encoding for the message
+   * @returns true if the toast is successfully sent, or nil and an error message if it fails
+   */
+  sendToastToPlayer(
+    message: string,
+    title: string,
+    username: string,
+    prefix?: string,
+    brackets?: string,
+    bracketColor?: string,
+    range?: number,
+    utf8Support?: boolean,
+  ): LuaMultiReturn<[boolean, string | undefined]>;
+
+  /**
+   * This function is fundamentally the same as sendMessage() except it takes a Minecraft text component as the first parameter.
+   * Find out more information on how the text component format works on the minecraft wiki. You can generate the json at minecraft.tools.
+   *
+   * @param json The Minecraft text component to send (as JSON string)
+   * @param prefix The prefix to display in brackets at the start of the message (defaults to "AP")
+   * @param brackets The bracket style around the prefix (e.g., "[]", "()", "<>")
+   * @param bracketColor The color for the brackets in MOTD code format
+   * @param range The range in blocks to send the message to players (if not global)
+   * @param utf8Support Whether to use UTF8 encoding for the message
+   * @returns true if the message is successfully sent, or nil and an error message if it fails
+   */
+  sendFormattedMessage(
+    json: string,
+    prefix?: string,
+    brackets?: string,
+    bracketColor?: string,
+    range?: number,
+    utf8Support?: boolean,
+  ): LuaMultiReturn<[boolean, string | undefined]>;
+
+  /**
+   * Similar to sendFormattedMessage() this sends a formatted message to one specific player. Specify the player to send the message to with the username parameter.
+   *
+   * @param json The Minecraft text component to send (as JSON string)
+   * @param username The username of the player to send the message to
+   * @param prefix The prefix to display in brackets at the start of the message (defaults to "AP")
+   * @param brackets The bracket style around the prefix (e.g., "[]", "()", "<>")
+   * @param bracketColor The color for the brackets in MOTD code format
+   * @param range The range in blocks to send the message to players (if not global)
+   * @param utf8Support Whether to use UTF8 encoding for the message
+   * @returns true if the message is successfully sent, or nil and an error message if it fails
+   */
+  sendFormattedMessageToPlayer(
+    json: string,
+    username: string,
+    prefix?: string,
+    brackets?: string,
+    bracketColor?: string,
+    range?: number,
+    utf8Support?: boolean,
+  ): LuaMultiReturn<[boolean, string | undefined]>;
+
+  /**
+   * This function is fundamentally the same as sendToast() except it takes a Minecraft text component as the first and second parameter.
+   * Find out more information on how the text component format works on the minecraft wiki. You can generate the json at minecraft.tools.
+   *
+   * @param messageJson The Minecraft text component for the message (as JSON string)
+   * @param titleJson The Minecraft text component for the title (as JSON string)
+   * @param username The username of the player to send the toast to
+   * @param prefix The prefix to display in brackets at the start of the message (defaults to "AP")
+   * @param brackets The bracket style around the prefix (e.g., "[]", "()", "<>")
+   * @param bracketColor The color for the brackets in MOTD code format
+   * @param range The range in blocks to send the message to players (if not global)
+   * @param utf8Support Whether to use UTF8 encoding for the message
+   * @returns true if the toast is successfully sent, or nil and an error message if it fails
+   */
+  sendFormattedToastToPlayer(
+    messageJson: string,
+    titleJson: string,
+    username: string,
+    prefix?: string,
+    brackets?: string,
+    bracketColor?: string,
+    range?: number,
+    utf8Support?: boolean,
+  ): LuaMultiReturn<[boolean, string | undefined]>;
+}

types/advanced-peripherals/index.d.ts

@@ -1,14 +1,3 @@
-declare interface BlockItemDetailData {
-  id: string;
-  tag: object;
-  Count: number;
-  Slot: number;
-}
-
-declare interface BlockDetailData {
-  Items: Record<number, BlockItemDetailData>;
-}
-
-declare class BlockReaderPeripheral {
-  getBlockData(): BlockDetailData;
-}
+/// <reference path="./block-reader.d.ts" />
+/// <reference path="./chat-box.d.ts" />
+/// <reference path="./player-detector.d.ts" />

types/advanced-peripherals/package.json

@@ -4,7 +4,7 @@
   "description": "TypeScript type definitions for base Advanced Peripherals APIs.",
   "types": "./index.d.ts",
   "files": [
-    "./index.d.ts"
+    "./*.d.ts"
   ],
   "author": "SikongJueluo",
   "license": "MIT"

types/advanced-peripherals/player-detector.d.ts

@@ -0,0 +1,276 @@
+/**
+ * Represents the Player Detector peripheral from Advanced Peripherals.
+ * Used to detect and track players in the world.
+ *
+ * @see https://docs.advanced-peripherals.de/0.7/peripherals/player_detector/
+ */
+/** @noSelf **/
+declare interface PlayerDetectorPeripheral extends IPeripheral {
+  /**
+   * Returns information about the player with the specified username.
+   *
+   * @param username The player's username to look up
+   * @returns A table containing player information, or nil if the player is not found
+   */
+  getPlayerPos(username: string): PlayerInfo | undefined;
+
+  /**
+   * Returns information about the player with the specified username.
+   * Alternative name for getPlayerPos.
+   *
+   * @param username The player's username to look up
+   * @returns A table containing player information, or nil if the player is not found
+   */
+  getPlayer(username: string): PlayerInfo | undefined;
+
+  /**
+   * Returns a list of all online players.
+   *
+   * @returns Table containing all online players as an array of usernames
+   */
+  getOnlinePlayers(): string[];
+
+  /**
+   * Returns a list of players within the given range of the peripheral.
+   *
+   * @param range The range to search for players
+   * @returns Array containing usernames of players within range
+   */
+  getPlayersInRange(range: number): string[];
+
+  /**
+   * Returns a list of players within the 2 positions posOne and posTwo.
+   *
+   * @param posOne Position with x, y, z coordinates
+   * @param posTwo Position with x, y, z coordinates
+   * @returns Array containing usernames of players within the specified coordinates
+   */
+  getPlayersInCoords(posOne: Coordinate, posTwo: Coordinate): string[];
+
+  /**
+   * Returns a list of players within a cuboid centered at the peripheral.
+   *
+   * @param w Width of the cuboid (x-axis)
+   * @param h Height of the cuboid (y-axis)
+   * @param d Depth of the cuboid (z-axis)
+   * @returns Array containing usernames of players within the specified cuboid
+   */
+  getPlayersInCubic(w: number, h: number, d: number): string[];
+
+  /**
+   * Returns true if the player whose username matches the provided username is within the given range of the peripheral.
+   *
+   * @param range The range to check
+   * @param username The player's username to check
+   * @returns Boolean indicating if the player is in range
+   */
+  isPlayerInRange(range: number, username: string): boolean;
+
+  /**
+   * Returns true if the player is within the 2 positions.
+   *
+   * @param posOne Position with x, y, z coordinates
+   * @param posTwo Position with x, y, z coordinates
+   * @param username The player's username to check
+   * @returns Boolean indicating if the player is in the specified coordinates
+   */
+  isPlayerInCoords(
+    posOne: Coordinate,
+    posTwo: Coordinate,
+    username: string,
+  ): boolean;
+
+  /**
+   * Returns true if the player is within the cuboid centered at the peripheral.
+   *
+   * @param w Width of the cuboid (x-axis)
+   * @param h Height of the cuboid (y-axis)
+   * @param d Depth of the cuboid (z-axis)
+   * @param username The player's username to check
+   * @returns Boolean indicating if the player is in the specified cuboid
+   */
+  isPlayerInCubic(w: number, h: number, d: number, username: string): boolean;
+
+  /**
+   * Returns true if there is any player in the given range.
+   *
+   * @param range The range to check
+   * @returns Boolean indicating if any player is in range
+   */
+  isPlayersInRange(range: number): boolean;
+
+  /**
+   * Returns true if any player is within the 2 positions.
+   *
+   * @param posOne Position with x, y, z coordinates
+   * @param posTwo Position with x, y, z coordinates
+   * @returns Boolean indicating if any player is in the specified coordinates
+   */
+  isPlayersInCoords(posOne: Coordinate, posTwo: Coordinate): boolean;
+
+  /**
+   * Returns true if any player is within the cuboid centered at the peripheral.
+   *
+   * @param w Width of the cuboid (x-axis)
+   * @param h Height of the cuboid (y-axis)
+   * @param d Depth of the cuboid (z-axis)
+   * @returns Boolean indicating if any player is in the specified cuboid
+   */
+  isPlayersInCubic(w: number, h: number, d: number): boolean;
+}
+
+/**
+ * Represents a coordinate in 3D space.
+ */
+declare interface Coordinate {
+  /**
+   * The x coordinate.
+   */
+  x: number;
+  /**
+   * The y coordinate.
+   */
+  y: number;
+  /**
+   * The z coordinate.
+   */
+  z: number;
+}
+
+/**
+ * Contains detailed information about a player.
+ */
+declare interface PlayerInfo {
+  /**
+   * The dimension the player is in.
+   */
+  dimension: string;
+  /**
+   * The height of the player's eyes.
+   */
+  eyeHeight: number;
+  /**
+   * The pitch of the player's head.
+   */
+  pitch: number;
+  /**
+   * The health of the player.
+   */
+  health: number;
+  /**
+   * The max health of the player.
+   */
+  maxHealth: number;
+  /**
+   * The air supply of the player.
+   */
+  airSupply: number;
+  /**
+   * The respawn position of the player.
+   */
+  respawnPosition: number;
+  /**
+   * The respawn dimension of the player.
+   */
+  respawnDimension: number;
+  /**
+   * The respawn angle of the player in degrees.
+   */
+  respawnAngle: number;
+  /**
+   * The yaw of the player's head.
+   */
+  yaw: number;
+  /**
+   * The x coordinate.
+   */
+  x: number;
+  /**
+   * The y coordinate.
+   */
+  y: number;
+  /**
+   * The z coordinate.
+   */
+  z: number;
+}
+
+/**
+ * Player click event type for the Player Detector peripheral.
+ * Fires when a player clicks on the block.
+ */
+declare interface PlayerClickEvent {
+  /**
+   * The name of the event.
+   */
+  event: "playerClick";
+  /**
+   * The username of the player who clicked the block.
+   */
+  username: string;
+  /**
+   * The name of the peripheral like playerDetector_4.
+   */
+  devicename: string;
+}
+
+/**
+ * Player join event type for the Player Detector peripheral.
+ * Fires when a player joins the world/a server.
+ */
+declare interface PlayerJoinEvent {
+  /**
+   * The name of the event.
+   */
+  event: "playerJoin";
+  /**
+   * The username of the player who joined.
+   */
+  username: string;
+  /**
+   * The resource id of the dimension the player is in.
+   */
+  dimension: string;
+}
+
+/**
+ * Player leave event type for the Player Detector peripheral.
+ * Fires when a player leaves the world/a server.
+ */
+declare interface PlayerLeaveEvent {
+  /**
+   * The name of the event.
+   */
+  event: "playerLeave";
+  /**
+   * The username of the player who left.
+   */
+  username: string;
+  /**
+   * The resource id of the dimension the player was in.
+   */
+  dimension: string;
+}
+
+/**
+ * Player changed dimension event type for the Player Detector peripheral.
+ * Fires when a player changes dimensions.
+ */
+declare interface PlayerChangedDimensionEvent {
+  /**
+   * The name of the event.
+   */
+  event: "playerChangedDimension";
+  /**
+   * The username of the player who changed dimensions.
+   */
+  username: string;
+  /**
+   * The resource id of the dimension the player was in.
+   */
+  fromDim: string;
+  /**
+   * The resource id of the dimension the player is in.
+   */
+  toDim: string;
+}

types/advanced-peripherals/shared.d.ts

@@ -0,0 +1,111 @@
+declare interface BlockItemDetailData {
+  id: string;
+  tag: object;
+  Count: number;
+  Slot: number;
+}
+
+declare interface BlockDetailData {
+  Items: Record<number, BlockItemDetailData>;
+}
+
+/**
+ * Minecraft Text Component format
+ * @see https://minecraft.wiki/w/Text_component_format
+ */
+declare type MinecraftColor =
+  | "black"
+  | "dark_blue"
+  | "dark_green"
+  | "dark_aqua"
+  | "dark_red"
+  | "dark_purple"
+  | "gold"
+  | "gray"
+  | "dark_gray"
+  | "blue"
+  | "green"
+  | "aqua"
+  | "red"
+  | "light_purple"
+  | "yellow"
+  | "white"
+  | "reset"; // RGB color in #RRGGBB format
+
+declare type MinecraftFont =
+  | "minecraft:default"
+  | "minecraft:uniform"
+  | "minecraft:alt";
+
+declare type ClickEventAction =
+  | "open_url"
+  | "open_file"
+  | "run_command"
+  | "suggest_command"
+  | "change_page"
+  | "copy_to_clipboard";
+
+declare type HoverEventAction = "show_text" | "show_item" | "show_entity";
+
+declare interface ClickEvent {
+  action: ClickEventAction;
+  value: string | number;
+}
+
+declare interface HoverEvent {
+  action: HoverEventAction;
+  contents?: unknown;
+  value?: unknown;
+}
+
+declare interface BaseTextComponent {
+  type?: "text" | "translatable" | "score" | "selector" | "keybind" | "nbt";
+  text?: string;
+  translate?: string;
+  with?: (MinecraftTextComponent | string)[];
+  score?: {
+    name: string;
+    objective: string;
+    value?: string;
+  };
+  selector?: string;
+  keybind?: string;
+  nbt?: string;
+  interpret?: boolean;
+  separator?: MinecraftTextComponent;
+  block?: string;
+  entity?: string;
+  storage?: string;
+
+  // Formatting
+  color?: MinecraftColor;
+  font?: MinecraftFont;
+  bold?: boolean;
+  italic?: boolean;
+  underlined?: boolean;
+  strikethrough?: boolean;
+  obfuscated?: boolean;
+  insertion?: string;
+  clickEvent?: ClickEvent;
+  hoverEvent?: HoverEvent;
+  shadow_color?: number;
+
+  // Nested components
+  extra?: MinecraftTextComponent[];
+}
+
+declare interface TextTextComponent extends BaseTextComponent {
+  type?: "text";
+  text: string;
+}
+
+declare interface TranslatableTextComponent extends BaseTextComponent {
+  type: "translatable";
+  translate: string;
+  with?: (MinecraftTextComponent | string)[];
+}
+
+declare type MinecraftTextComponent =
+  | TextTextComponent
+  | TranslatableTextComponent
+  | BaseTextComponent;