redscript-mc 1.2.15 → 1.2.17

package/editors/vscode/builtins.d.mcrs

@@ -0,0 +1,494 @@
+// builtins.d.mcrs
+// RedScript builtin function declarations
+// Auto-generated by: redscript generate-dts
+// DO NOT EDIT — regenerate with: redscript generate-dts
+
+// ──────────────────────────────────────────────────────────────────────
+// Chat & Display
+// ──────────────────────────────────────────────────────────────────────
+
+/// Displays a message to all players in chat as the server.
+/// @param message Message to broadcast to all players
+/// @example say("Hello, world!");
+/// @example say("Game has started!");
+declare fn say(message: string): void;
+
+/// Sends a private message to a player or selector using tellraw.
+/// @param target Target player or entity selector
+/// @param message Message to send privately
+/// @example tell(@s, "You won!");
+/// @example tell(@a[tag=vip], "Welcome, VIP!");
+declare fn tell(target: selector, message: string): void;
+
+/// Alias for tell(). Sends a raw text message using tellraw.
+/// @param target Target player or entity selector
+/// @param message Message text (supports f-string interpolation)
+/// @example tellraw(@s, "Hello!");
+declare fn tellraw(target: selector, message: string): void;
+
+/// Sends a message to all players in chat (@a).
+/// @param message Message to broadcast
+/// @example announce("Round 1 starts in 3 seconds!");
+declare fn announce(message: string): void;
+
+/// Shows a large title on screen for target players.
+/// @param target Target player(s)
+/// @param message Title text to display
+/// @example title(@a, "Round 1");
+/// @example title(@s, "You Win!");
+declare fn title(target: selector, message: string): void;
+
+/// Shows subtitle text below the main title on screen.
+/// @param target Target player(s)
+/// @param message Subtitle text (appears below title)
+/// @example subtitle(@a, "Fight!");
+declare fn subtitle(target: selector, message: string): void;
+
+/// Displays text in the action bar (above the hotbar).
+/// @param target Target player(s)
+/// @param message Action bar text (above hotbar)
+/// @example actionbar(@a, "⏱ ${time}s remaining");
+declare fn actionbar(target: selector, message: string): void;
+
+/// Sets title display timing in ticks. 20 ticks = 1 second.
+/// @param target Target player(s)
+/// @param fadeIn Fade-in duration in ticks
+/// @param stay Stay duration in ticks
+/// @param fadeOut Fade-out duration in ticks
+/// @example title_times(@a, 10, 40, 10);
+/// @example // Show for 2 seconds
+declare fn title_times(target: selector, fadeIn: int, stay: int, fadeOut: int): void;
+
+// ──────────────────────────────────────────────────────────────────────
+// Player
+// ──────────────────────────────────────────────────────────────────────
+
+/// Gives item(s) to a player.
+/// @param target Target player(s)
+/// @param item Item ID (e.g. "minecraft:diamond")
+/// @param count Number of items to give (optional)
+/// @param nbt Optional NBT data for the item (optional)
+/// @example give(@s, "minecraft:diamond", 5);
+/// @example give(@a, "minecraft:apple");
+/// @example give(@s, "minecraft:diamond_sword", 1, "{Enchantments:[{id:\"minecraft:sharpness\",lvl:5s}]}");
+declare fn give(target: selector, item: string, count: int = 1, nbt: string): void;
+
+/// Kills the target entity. Defaults to the executing entity (@s).
+/// @param target Target to kill (default: @s) (optional)
+/// @example kill(@e[type=minecraft:zombie]);
+/// @example kill(@s);
+/// @example kill(@e[tag=enemy]);
+declare fn kill(target: selector = @s): void;
+
+/// Applies a status effect to an entity.
+/// @param target Target entity or player
+/// @param effect Effect ID (e.g. "minecraft:speed")
+/// @param duration Duration in seconds (optional)
+/// @param amplifier Effect level (0-255, where 0 = level 1) (optional)
+/// @example effect(@s, "minecraft:speed", 60, 1);
+/// @example effect(@a, "minecraft:regeneration", 10);
+/// @example effect(@e[type=minecraft:zombie], "minecraft:slowness", 20, 2);
+declare fn effect(target: selector, effect: string, duration: int = 30, amplifier: int = 0): void;
+
+/// Removes a status effect from an entity, or clears all effects.
+/// @param target Target entity or player
+/// @param effect Effect to remove (omit to clear all) (optional)
+/// @example effect_clear(@s, "minecraft:poison");
+/// @example effect_clear(@a);
+declare fn effect_clear(target: selector, effect: string): void;
+
+/// Removes items from a player's inventory.
+/// @param target Target player
+/// @param item Specific item to remove (omit to clear all) (optional)
+/// @example clear(@s, "minecraft:dirt");
+/// @example clear(@a);
+declare fn clear(target: selector, item: string): void;
+
+/// Kicks a player from the server with an optional reason.
+/// @param player Target player to kick
+/// @param reason Kick message shown to the player (optional)
+/// @example kick(@s, "You lost!");
+/// @example kick(@p, "AFK too long");
+declare fn kick(player: selector, reason: string): void;
+
+/// Adds experience points or levels to a player.
+/// @param target Target player
+/// @param amount Amount of XP to add
+/// @param type "points" or "levels" (optional)
+/// @example xp_add(@s, 100);
+/// @example xp_add(@s, 5, "levels");
+declare fn xp_add(target: selector, amount: int, type: string = points): void;
+
+/// Sets a player's experience points or levels.
+/// @param target Target player
+/// @param amount New XP value
+/// @param type "points" or "levels" (optional)
+/// @example xp_set(@s, 0, "levels");
+/// @example xp_set(@s, 500);
+declare fn xp_set(target: selector, amount: int, type: string = points): void;
+
+// ──────────────────────────────────────────────────────────────────────
+// World & Block
+// ──────────────────────────────────────────────────────────────────────
+
+/// Teleports an entity to a player or position.
+/// @param target Entity to teleport
+/// @param destination Target player or BlockPos coordinates
+/// @example tp(@s, (0, 64, 0));
+/// @example tp(@a, @s);
+/// @example tp(@s, (~0, ~10, ~0));
+declare fn tp(target: selector, destination: selector): void;
+
+/// @deprecated Use tp() instead. Teleports an entity to a position.
+/// @param target Entity to teleport
+/// @param destination Target player or position
+/// @example tp(@s, (0, 64, 0));  // use tp instead
+declare fn tp_to(target: selector, destination: selector): void;
+
+/// Places a block at the specified coordinates.
+/// @param pos Block position, e.g. (0, 64, 0) or (~1, ~0, ~0)
+/// @param block Block ID (e.g. "minecraft:stone")
+/// @example setblock((0, 64, 0), "minecraft:stone");
+/// @example setblock((~1, ~0, ~0), "minecraft:air");
+declare fn setblock(pos: BlockPos, block: string): void;
+
+/// Fills a cuboid region with a specified block.
+/// @param from Start corner of the region
+/// @param to End corner of the region
+/// @param block Block to fill with
+/// @example fill((0, 64, 0), (10, 64, 10), "minecraft:grass_block");
+/// @example fill((~-5, ~-1, ~-5), (~5, ~-1, ~5), "minecraft:bedrock");
+declare fn fill(from: BlockPos, to: BlockPos, block: string): void;
+
+/// Clones a region of blocks to a new location.
+/// @param from Source region start corner
+/// @param to Source region end corner
+/// @param dest Destination corner
+/// @example clone((0,64,0), (10,64,10), (20,64,0));
+declare fn clone(from: BlockPos, to: BlockPos, dest: BlockPos): void;
+
+/// Summons an entity at the specified position.
+/// @param type Entity type ID (e.g. "minecraft:zombie")
+/// @param x X coordinate (default: ~) (optional)
+/// @param y Y coordinate (default: ~) (optional)
+/// @param z Z coordinate (default: ~) (optional)
+/// @param nbt Optional NBT data for the entity (optional)
+/// @example summon("minecraft:zombie", ~0, ~0, ~0);
+/// @example summon("minecraft:armor_stand", (0, 64, 0));
+/// @example summon("minecraft:zombie", ~0, ~0, ~0, "{CustomName:\"Boss\"}");
+declare fn summon(type: string, x: coord = ~, y: coord = ~, z: coord = ~, nbt: string): void;
+
+/// Spawns a particle effect at the specified position.
+/// @param name Particle type ID (e.g. "minecraft:flame")
+/// @param x X coordinate (optional)
+/// @param y Y coordinate (optional)
+/// @param z Z coordinate (optional)
+/// @example particle("minecraft:flame", (~0, ~1, ~0));
+/// @example particle("minecraft:explosion", (0, 100, 0));
+declare fn particle(name: string, x: coord = ~, y: coord = ~, z: coord = ~): void;
+
+/// Plays a sound effect for target players.
+/// @param sound Sound event ID (e.g. "entity.experience_orb.pickup")
+/// @param source Sound category: "master", "music", "record", "weather", "block", "hostile", "neutral", "player", "ambient", "voice"
+/// @param target Target player to hear the sound
+/// @param x X origin position (optional)
+/// @param y Y origin position (optional)
+/// @param z Z origin position (optional)
+/// @param volume Volume (default: 1.0) (optional)
+/// @param pitch Pitch (default: 1.0) (optional)
+/// @param minVolume Minimum volume for distant players (optional)
+/// @example playsound("entity.experience_orb.pickup", "player", @s);
+/// @example playsound("ui.toast.challenge_complete", "master", @a);
+declare fn playsound(sound: string, source: string, target: selector, x: coord, y: coord, z: coord, volume: float = 1.0, pitch: float = 1.0, minVolume: float): void;
+
+/// Sets the weather condition.
+/// @param type "clear", "rain", or "thunder"
+/// @example weather("clear");
+/// @example weather("thunder");
+declare fn weather(type: string): void;
+
+/// Sets the world time.
+/// @param value Time in ticks, or "day"/"night"/"noon"/"midnight"
+/// @example time_set(0);  // dawn
+/// @example time_set("midnight");
+declare fn time_set(value: string): void;
+
+/// Advances the world time by a number of ticks.
+/// @param ticks Number of ticks to advance
+/// @example time_add(6000);  // advance by half a day
+declare fn time_add(ticks: int): void;
+
+/// Sets a gamerule value.
+/// @param rule Gamerule name (e.g. "keepInventory")
+/// @param value New value (true/false for boolean rules, integer for numeric)
+/// @example gamerule("keepInventory", true);
+/// @example gamerule("randomTickSpeed", 3);
+declare fn gamerule(rule: string, value: string): void;
+
+/// Sets the game difficulty.
+/// @param level "peaceful", "easy", "normal", or "hard"
+/// @example difficulty("hard");
+/// @example difficulty("peaceful");
+declare fn difficulty(level: string): void;
+
+// ──────────────────────────────────────────────────────────────────────
+// Entities & Tags
+// ──────────────────────────────────────────────────────────────────────
+
+/// Adds a scoreboard tag to an entity.
+/// @param target Target entity
+/// @param tag Tag name to add
+/// @example tag_add(@s, "hasKey");
+/// @example tag_add(@e[type=minecraft:zombie], "boss");
+declare fn tag_add(target: selector, tag: string): void;
+
+/// Removes a scoreboard tag from an entity.
+/// @param target Target entity
+/// @param tag Tag name to remove
+/// @example tag_remove(@s, "hasKey");
+declare fn tag_remove(target: selector, tag: string): void;
+
+// ──────────────────────────────────────────────────────────────────────
+// Scoreboard
+// ──────────────────────────────────────────────────────────────────────
+
+/// Reads a value from a vanilla MC scoreboard objective.
+/// @param target Player, entity, or fake player name (e.g. "#counter")
+/// @param objective Scoreboard objective name
+/// @returns int
+/// @example let hp: int = scoreboard_get(@s, "health");
+/// @example let kills: int = scoreboard_get(@s, "kills");
+declare fn scoreboard_get(target: selector, objective: string): int;
+
+/// Alias for scoreboard_get(). Reads a value from a scoreboard.
+/// @param target Player, entity, or fake player name
+/// @param objective Scoreboard objective name
+/// @returns int
+/// @example let kills: int = score(@s, "kills");
+declare fn score(target: selector, objective: string): int;
+
+/// Sets a value in a vanilla MC scoreboard objective.
+/// @param target Player, entity, or fake player
+/// @param objective Objective name
+/// @param value New score value
+/// @example scoreboard_set("#game", "timer", 300);
+/// @example scoreboard_set(@s, "lives", 3);
+declare fn scoreboard_set(target: selector, objective: string, value: int): void;
+
+/// Displays a scoreboard objective in a display slot.
+/// @param slot "list", "sidebar", or "belowName"
+/// @param objective Objective name to display
+/// @example scoreboard_display("sidebar", "kills");
+declare fn scoreboard_display(slot: string, objective: string): void;
+
+/// Clears the display in a scoreboard slot.
+/// @param slot "list", "sidebar", or "belowName"
+/// @example scoreboard_hide("sidebar");
+declare fn scoreboard_hide(slot: string): void;
+
+/// Creates a new scoreboard objective.
+/// @param name Objective name
+/// @param criteria Criteria (e.g. "dummy", "playerKillCount")
+/// @param displayName Optional display name (optional)
+/// @example scoreboard_add_objective("kills", "playerKillCount");
+/// @example scoreboard_add_objective("timer", "dummy", "Game Timer");
+declare fn scoreboard_add_objective(name: string, criteria: string, displayName: string): void;
+
+/// Removes a scoreboard objective.
+/// @param name Objective name to remove
+/// @example scoreboard_remove_objective("kills");
+declare fn scoreboard_remove_objective(name: string): void;
+
+// ──────────────────────────────────────────────────────────────────────
+// Random
+// ──────────────────────────────────────────────────────────────────────
+
+/// Generates a random integer in range [min, max] using scoreboard arithmetic. Compatible with all MC versions.
+/// @param min Minimum value (inclusive)
+/// @param max Maximum value (inclusive)
+/// @returns int
+/// @example let roll: int = random(1, 6);
+/// @example let chance: int = random(0, 99);
+declare fn random(min: int, max: int): int;
+
+/// Generates a random integer using /random command (MC 1.20.3+). Faster and more reliable than random().
+/// @param min Minimum value (inclusive)
+/// @param max Maximum value (inclusive)
+/// @returns int
+/// @example let n: int = random_native(1, 100);
+declare fn random_native(min: int, max: int): int;
+
+/// Resets a random sequence with an optional seed (MC 1.20.3+).
+/// @param sequence Sequence name (namespaced, e.g. "mypack:loot")
+/// @param seed Seed value (optional)
+/// @example random_sequence("mypack:loot", 42);
+declare fn random_sequence(sequence: string, seed: int = 0): void;
+
+// ──────────────────────────────────────────────────────────────────────
+// Data (NBT)
+// ──────────────────────────────────────────────────────────────────────
+
+/// Reads NBT data from an entity, block, or storage into an integer variable.
+/// @param targetType "entity", "block", or "storage"
+/// @param target Target selector or storage path
+/// @param path NBT path (e.g. "Health")
+/// @param scale Scale factor (optional)
+/// @returns int
+/// @example let hp: int = data_get("entity", "@s", "Health");
+/// @example let val: int = data_get("storage", "mypack:data", "myKey");
+declare fn data_get(targetType: string, target: string, path: string, scale: float = 1): int;
+
+/// Merges NBT data into an entity, block, or storage.
+/// @param target Target entity selector or block position
+/// @param nbt NBT data to merge (struct literal or string)
+/// @example data_merge(@s, { Invisible: 1b, Silent: 1b });
+declare fn data_merge(target: selector, nbt: string): void;
+
+// ──────────────────────────────────────────────────────────────────────
+// Boss Bar
+// ──────────────────────────────────────────────────────────────────────
+
+/// Creates a new boss bar.
+/// @param id Boss bar ID (namespaced, e.g. "minecraft:health")
+/// @param name Display name
+/// @example bossbar_add("mymod:timer", "Time Left");
+declare fn bossbar_add(id: string, name: string): void;
+
+/// Sets the current value of a boss bar.
+/// @param id Boss bar ID
+/// @param value Current value
+/// @example bossbar_set_value("mymod:timer", 60);
+declare fn bossbar_set_value(id: string, value: int): void;
+
+/// Sets the maximum value of a boss bar.
+/// @param id Boss bar ID
+/// @param max Maximum value
+/// @example bossbar_set_max("mymod:timer", 300);
+declare fn bossbar_set_max(id: string, max: int): void;
+
+/// Sets the color of a boss bar.
+/// @param id Boss bar ID
+/// @param color "blue", "green", "pink", "purple", "red", "white", or "yellow"
+/// @example bossbar_set_color("mymod:timer", "red");
+declare fn bossbar_set_color(id: string, color: string): void;
+
+/// Sets the style (segmentation) of a boss bar.
+/// @param id Boss bar segmentation style
+/// @param style "notched_6", "notched_10", "notched_12", "notched_20", or "progress"
+/// @example bossbar_set_style("mymod:timer", "notched_10");
+declare fn bossbar_set_style(id: string, style: string): void;
+
+/// Shows or hides a boss bar.
+/// @param id Boss bar ID
+/// @param visible Visibility state (true = show, false = hide)
+/// @example bossbar_set_visible("mymod:timer", true);
+declare fn bossbar_set_visible(id: string, visible: bool): void;
+
+/// Sets which players can see the boss bar.
+/// @param id Boss bar ID
+/// @param target Players who should see the boss bar
+/// @example bossbar_set_players("mymod:timer", @a);
+declare fn bossbar_set_players(id: string, target: selector): void;
+
+/// Removes a boss bar.
+/// @param id Boss bar ID to remove
+/// @example bossbar_remove("mymod:timer");
+declare fn bossbar_remove(id: string): void;
+
+/// Gets the current value of a boss bar.
+/// @param id Boss bar ID
+/// @returns int
+/// @example let v: int = bossbar_get_value("mymod:timer");
+declare fn bossbar_get_value(id: string): int;
+
+// ──────────────────────────────────────────────────────────────────────
+// Teams
+// ──────────────────────────────────────────────────────────────────────
+
+/// Creates a new team.
+/// @param name Team name
+/// @param displayName Optional display name (optional)
+/// @example team_add("red");
+/// @example team_add("blue", "Blue Team");
+declare fn team_add(name: string, displayName: string): void;
+
+/// Removes a team.
+/// @param name Team name to remove
+/// @example team_remove("red");
+declare fn team_remove(name: string): void;
+
+/// Adds entities to a team.
+/// @param name Team name to join
+/// @param target Entities to add to the team
+/// @example team_join("red", @s);
+/// @example team_join("blue", @a[tag=blue_team]);
+declare fn team_join(name: string, target: selector): void;
+
+/// Removes entities from their current team.
+/// @param target Entities to remove from their team
+/// @example team_leave(@s);
+declare fn team_leave(target: selector): void;
+
+/// Sets a team option/property.
+/// @param name Team name
+/// @param option Option name (e.g. "color", "friendlyFire", "prefix")
+/// @param value Option value
+/// @example team_option("red", "color", "red");
+/// @example team_option("blue", "friendlyFire", "false");
+declare fn team_option(name: string, option: string, value: string): void;
+
+// ──────────────────────────────────────────────────────────────────────
+// Collections (Set)
+// ──────────────────────────────────────────────────────────────────────
+
+/// Creates a new unique set backed by NBT storage. Returns the set ID.
+/// @returns string
+/// @example let enemies: string = set_new();
+/// @example set_add(enemies, "@s");
+declare fn set_new(): string;
+
+/// Adds a value to a set (no-op if already present).
+/// @param setId Set ID returned by set_new()
+/// @param value Value to add
+/// @example set_add(enemies, "@s");
+declare fn set_add(setId: string, value: string): void;
+
+/// Returns 1 if the set contains the value, 0 otherwise.
+/// @param setId Set ID
+/// @param value Value to check
+/// @returns int
+/// @example if set_contains(enemies, "@s") { kill(@s); }
+declare fn set_contains(setId: string, value: string): int;
+
+/// Removes a value from a set.
+/// @param setId Set ID
+/// @param value Value to remove
+/// @example set_remove(enemies, "@s");
+declare fn set_remove(setId: string, value: string): void;
+
+/// Removes all values from a set.
+/// @param setId Set ID to clear
+/// @example set_clear(enemies);
+declare fn set_clear(setId: string): void;
+
+// ──────────────────────────────────────────────────────────────────────
+// Timers
+// ──────────────────────────────────────────────────────────────────────
+
+/// Executes a callback function after a delay (in ticks).
+/// @param delay Delay in ticks before executing the callback
+/// @param callback Lambda function to execute after delay
+/// @example setTimeout(100, () => { say("5 seconds passed!"); });
+declare fn setTimeout(delay: int, callback: string): void;
+
+/// Executes a callback function repeatedly at a fixed interval. Returns an interval ID.
+/// @param interval Interval in ticks between executions
+/// @param callback Lambda function to execute repeatedly
+/// @returns int
+/// @example let timer: int = setInterval(20, () => { say("Every second!"); });
+declare fn setInterval(interval: int, callback: string): int;
+
+/// Cancels a repeating interval created by setInterval().
+/// @param id Interval ID returned by setInterval()
+/// @example clearInterval(timer);
+declare fn clearInterval(id: int): void;