Script API - v26.60
    Preparing search index...

    Class ObservableString

    An observable that holds a string value. Listeners are notified whenever the value changes.

    import { Player, system } from "@minecraft/server";
    import { CustomForm, DataDrivenScreenClosedReason, ObservableString } from "@minecraft/server-ui";

    // Run `/scriptevent example:guildtageditor` in chat to open the form.
    system.afterEvents.scriptEventReceive.subscribe(({ id, sourceEntity }) => {
    if (id !== "example:guildtageditor" || !(sourceEntity instanceof Player)) return;

    const guildTag = new ObservableString("Vanguard", { clientWritable: true });
    guildTag.subscribe((text) => {
    sourceEntity.sendMessage(`Guild tag updated: ${text}`);
    });

    const form = new CustomForm(sourceEntity, "Guild Editor");
    form.textField("Guild Tag", guildTag);

    form.show().then((reason) => {
    if (reason === DataDrivenScreenClosedReason.ServerClosed) {
    sourceEntity.sendMessage("The server closed the guild editor.");
    } else {
    sourceEntity.sendMessage("You closed the guild editor.");
    }
    });
    });
    export class ObservableString {
    constructor(data: string, options?: ObservableOptions);
    getData(): string;
    getFilteredText(player: minecraftserver.Player): Promise<TextFilteringError[] | string>;
    setData(data: string): void;
    subscribe(callback: (arg0: string) => void): (arg0: string) => void;
    unsubscribe(callback: (arg0: string) => void): boolean;
    }
    Index
    • Parameters

      • data: string

        The initial string value for this observable. Maximum Length: 5000

      • Optionaloptions: ObservableOptions

        Optional configuration for the observable, such as whether the value can be written by the client.

      Returns ObservableString

      Creates a new ObservableString with the provided initial string value.

      This function can't be called in restricted-execution mode.

      early-execution-allowed - This function can be called in early-execution mode.

    • Returns string

      Returns the current string value held by this observable.

      This function can't be called in restricted-execution mode.

      early-execution-allowed - This function can be called in early-execution mode.

      import { Player, system } from "@minecraft/server";
      import { ObservableString } from "@minecraft/server-ui";

      // Run `/scriptevent example:playerstatus` in chat to try this example.
      system.afterEvents.scriptEventReceive.subscribe(({ id, sourceEntity }) => {
      if (id !== "example:playerstatus" || !(sourceEntity instanceof Player)) return;

      const statusNote = new ObservableString("Exploring Cave");
      const currentStatus = statusNote.getData();
      sourceEntity.sendMessage(`Player status: ${currentStatus}`);
      });
    • Parameters

      Returns Promise<string | TextFilteringError[]>

      Gets filtered data from the Observable (only available for strings). In case of failure, it will return an array of TextFilteringError that can provide more context about the filtering process. For testing purposes, the options are available under 'Creator -> Text Filtering' settings menu. This delay is only applied to the getFilteredText function and can be used to simulate network latency when testing.

      This function can't be called in restricted-execution mode.

      This function can throw errors.

      minecraftcommon.EngineError

      minecraftserver.InvalidEntityError

      This function can't be called in early-execution mode.

      import { Player, system } from "@minecraft/server";
      import { ObservableString } from "@minecraft/server-ui";

      // Run `/scriptevent example:filterchatmessage` in chat to try this example.
      system.afterEvents.scriptEventReceive.subscribe(({ id, sourceEntity }) => {
      if (id !== "example:filterchatmessage" || !(sourceEntity instanceof Player)) return;

      const chatMessage = new ObservableString("Hello world", { clientWritable: true });

      // Check the string against Minecraft text filtering rules for the player.
      chatMessage.getFilteredText(sourceEntity).then((filteredResult) => {
      if (typeof filteredResult === "string") {
      sourceEntity.sendMessage(`Filtered message: ${filteredResult}`);
      } else {
      sourceEntity.sendMessage("Text filtering blocked the message.");
      }
      });
      });
    • Parameters

      • data: string

        The new string value to set. Maximum Length: 5000

      Returns void

      Updates the string value held by this observable. If the new value differs from the current value, all subscribed listeners are notified with the new value.

      This function can't be called in restricted-execution mode.

      early-execution-allowed - This function can be called in early-execution mode.

      import { Player, system } from "@minecraft/server";
      import { ObservableString } from "@minecraft/server-ui";

      // Run `/scriptevent example:matchstatus` in chat to try this example.
      system.afterEvents.scriptEventReceive.subscribe(({ id, sourceEntity }) => {
      if (id !== "example:matchstatus" || !(sourceEntity instanceof Player)) return;

      const titleMessage = new ObservableString("Starting Match");
      titleMessage.subscribe((newTitle) => {
      sourceEntity.sendMessage(`Title changed to: ${newTitle}`);
      });

      titleMessage.setData("Match in Progress");
      });
    • Parameters

      • callback: (arg0: string) => void

        A function that receives the new string value each time the observable changes.

      Returns (arg0: string) => void

      Registers a callback to be invoked whenever the observable's value changes. Returns the callback, which can be passed to unsubscribe to remove the listener.

      This function can't be called in restricted-execution mode.

      early-execution-allowed - This function can be called in early-execution mode.

      import { Player, system } from "@minecraft/server";
      import { CustomForm, ObservableString } from "@minecraft/server-ui";

      const titles = ["Novice", "Adventurer", "Champion", "Legend"];

      // Run `/scriptevent example:ranktitle` in chat to open the form.
      system.afterEvents.scriptEventReceive.subscribe(({ id, sourceEntity }) => {
      if (id !== "example:ranktitle" || !(sourceEntity instanceof Player)) return;

      const playerTitle = new ObservableString("Novice");
      // `subscribe` returns the callback. Keep it so `unsubscribe` can remove the same listener.
      const listener = playerTitle.subscribe((title) => {
      sourceEntity.sendMessage(`Rank title updated to ${title}.`);
      });

      const form = new CustomForm(sourceEntity, "Player Rank");
      form.button("Unsubscribe", () => playerTitle.unsubscribe(listener));
      form.button("Subscribe", () => playerTitle.subscribe(listener));

      // Pick a random title every 2 seconds (40 ticks) so the listener receives updates while subscribed.
      const intervalId = system.runInterval(() => {
      playerTitle.setData(titles[Math.floor(Math.random() * titles.length)]);
      }, 40);

      // `show` resolves when the player closes the form. Stop the changes then.
      form.show().then(() => system.clearRun(intervalId));
      });
    • Parameters

      • callback: (arg0: string) => void

        The callback handle previously returned by subscribe.

      Returns boolean

      Removes a previously registered listener from this observable. Returns true if the listener was found and removed, false if it was not found.

      This function can't be called in restricted-execution mode.

      early-execution-allowed - This function can be called in early-execution mode.

      import { Player, system } from "@minecraft/server";
      import { CustomForm, ObservableString } from "@minecraft/server-ui";

      const statuses = ["Online", "Away", "In Minigame", "Offline"];

      // Run `/scriptevent example:presencestatus` in chat to open the form.
      system.afterEvents.scriptEventReceive.subscribe(({ id, sourceEntity }) => {
      if (id !== "example:presencestatus" || !(sourceEntity instanceof Player)) return;

      const playerStatus = new ObservableString("Online");
      const listener = playerStatus.subscribe((status) => {
      sourceEntity.sendMessage(`Status changed to ${status}.`);
      });

      const form = new CustomForm(sourceEntity, "Presence Status");
      // `unsubscribe` removes the listener so it stops receiving changes.
      form.button("Unsubscribe", () => playerStatus.unsubscribe(listener));
      form.button("Subscribe", () => playerStatus.subscribe(listener));

      // Pick a random status every 2 seconds (40 ticks) so the listener receives updates while subscribed.
      const intervalId = system.runInterval(() => {
      playerStatus.setData(statuses[Math.floor(Math.random() * statuses.length)]);
      }, 40);

      // `show` resolves when the player closes the form. Stop the changes then.
      form.show().then(() => system.clearRun(intervalId));
      });