Class Observable<T>`Beta`

A class that represents data that can be Observed. Extensively used for UI.

Example: dynamicLabel.ts

// Adapted from Microsoft's DDUI intro doc:
// https://learn.microsoft.com/en-us/minecraft/creator/documents/scripting/intro-to-ddui
import { CustomForm, Observable } from "@minecraft/server-ui";
import { CommandPermissionLevel, CustomCommandStatus, Player, system } from "@minecraft/server";

const statusLabel = Observable.create<string>("Ready");
const itemCount = Observable.create<number>(0);

// Whenever itemCount changes, the label text updates too.
itemCount.subscribe((count) => {
   statusLabel.setData(`Found ${count} items`);
});

// Run /test:dynamiclabel in chat.
system.beforeEvents.startup.subscribe((event) => {
   event.customCommandRegistry.registerCommand(
       {
           name: "test:dynamiclabel",
           description: "Show a form with a label bound to an Observable",
           permissionLevel: CommandPermissionLevel.Any,
       },
       (origin) => {
           const player = origin.sourceEntity;
           if (!(player instanceof Player)) {
               return {
                   message: "This command can only be used by a player.",
                   status: CustomCommandStatus.Failure,
               };
           }

           // Demo update so beginners can immediately see label changes.
           itemCount.setData(Math.floor(Math.random() * 10) + 1);

           CustomForm.create(player, "Inventory")
               .label(statusLabel)
               .button("Refresh", () => {
                   itemCount.setData(Math.floor(Math.random() * 10) + 1);
               })
               .closeButton()
               .show()
               .catch((e) => {
                   console.error(e);
               });

           return {
               message: "Opening dynamic label demo...",
               status: CustomCommandStatus.Success,
           };
       }
   );
});

Example: subscribeToChanges.ts

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

const selectedOption = Observable.create<number>(0, { clientWritable: true });

selectedOption.subscribe((newValue) => {
   console.log(`Selection changed to: ${newValue}`);
});

// Simulate a change from a player
system.beforeEvents.startup.subscribe((event) => {
   event.customCommandRegistry.registerCommand(
       {
           name: "test:changeoption",
           description: "Change the selected option",
           permissionLevel: 0,
       },
       (origin) => {
           const player = origin.sourceEntity;
           if (!(player instanceof Player)) {
               return {
                   message: "This command can only be used by a player.",
                   status: CustomCommandStatus.Failure,
               };
           }
           system.run(() => {
               const form = CustomForm.create(player, "Change Option");
               form.dropdown("Select an option", selectedOption, [
                   { label: "Option 1", value: 0 },
                   { label: "Option 2", value: 1 },
                   { label: "Option 3", value: 2 },
               ]);
               form.show().catch((e) => console.error(e));
           });
           return {
               message: "Creating form...",
               status: CustomCommandStatus.Success,
           };
       }
   );
});

Example: updateValues.ts

import { Observable } from "@minecraft/server-ui";
import { system, world } from "@minecraft/server";

// Create an Observable to track the number of entities in the dimension
const entityCount = Observable.create<number>(0);

// Update the value - UI automatically reflects the change
system.runInterval(() => {
   const entities = world.getDimension("overworld").getEntities();
   entityCount.setData(entities.length);
}, 20);

Important

Colour codes are only supported by the non-blurry Ore UI text (form title, header and label)
Glyphs are not supported by Ore UI at all

Type Parameters

T extends string | number | boolean | UIRawMessage

Index

Constructors

constructor

Methods

getData getFilteredText setData subscribe toJSON unsubscribe create

Constructors

constructor

new Observable<T extends string | number | boolean | UIRawMessage>(): Observable<
T,
>
Type Parameters
- T extends string | number | boolean | UIRawMessage
Returns Observable<T>

Methods

getData

getData(): T
Returns T
Remarks
Gets the data from the Observable.

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

getFilteredText

getFilteredText(
this: Observable<T & string>,
player: Player,
): Promise<string | TextFilteringError[]>
Parameters
- this: Observable<T & string>
- player: Player
Returns Promise<string | TextFilteringError[]>
Remarks
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.

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

setData

setData(data: T): void
Parameters
- data: T
Returns void
Remarks
Sets the data on this Observable and notifies the subscribers.

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

subscribe(listener: (newValue: T) => void): (newValue: T) => void
Parameters
- listener: (newValue: T) => void
Returns (newValue: T) => void
Remarks
Subscribes a callback to any changes that occur to the Observable. The return value can be passed into the unsubscribe function to stop listening to changes.

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

toJSON

toJSON(): unknown
Returns unknown

unsubscribe

unsubscribe(listener: (newValue: T) => void): void
Parameters
- listener: (newValue: T) => void
Returns void
Remarks
Unsubscribe a callback from any changes that occur to the Observable. This takes the return value from the subscribe function.

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

`Static`create

create<T extends string | number | boolean | UIRawMessage>(
data: T,
options?: ObservableOptions,
): Observable<T>
Type Parameters
- T extends string | number | boolean | UIRawMessage
Parameters
- data: T
- Optionaloptions: ObservableOptions
Returns Observable<T>
Remarks
Creates an Observable, use this instead of a constructor.

World Ready
This function can't be called in early-execution mode.
Example: example.ts
```
import { Observable } from "@minecraft/server-ui";

// Read-only Observable (server controls the value)
const status = Observable.create<string>("Loading...");

// Client-writable Observable (UI controls can update it)
const userInput = Observable.create<string>("", { clientWritable: true });
```

Class Observable<T>Beta

Example: dynamicLabel.ts

Example: subscribeToChanges.ts

Example: updateValues.ts

Type Parameters

Index

Constructors

Methods

Constructors

constructor

Type Parameters

Returns Observable<T>

Methods

getData

Returns T

Remarks

World Ready

getFilteredText

Parameters

Returns Promise<string | TextFilteringError[]>

Remarks

World Ready

setData

Parameters

Returns void

Remarks

World Ready

subscribe

Parameters

Returns (newValue: T) => void

Remarks

World Ready

toJSON

Returns unknown

unsubscribe

Parameters

Returns void

Remarks

World Ready

Staticcreate

Type Parameters

Parameters

Returns Observable<T>

Remarks

World Ready

Example: example.ts

Settings

On This Page

Class Observable<T>`Beta`

`Static`create