Svelte-библиотека

@webgui/svelte предоставляет сторы Svelte и TypeScript-типы для SPA, работающих внутри мода WebGUI. Отдаёт внедряемый window.webgui в виде сторов, которые читаются через синтаксис $ — без бойлерплейта.

Одни данные, разные фреймворки

@webgui/svelte, @webgui/react и @webgui/vue отдают одни и те же данные и действия — бери под свой фреймворк. Полные формы WebGUIClient / WebGUIEntity описаны на странице React-библиотека.

Установка

npm install @webgui/svelte

Требует Svelte 4+ как peer-зависимость. Версия пакета совпадает с версией мода (например, @webgui/svelte@1.6.0 — под WebGUI 1.6.0).

Быстрый старт

<script lang="ts">
  import { webguiClient, isInMod } from '@webgui/svelte'
</script>

{#if !isInMod()}
  <p>Откройте страницу внутри Minecraft.</p>
{:else if $webguiClient}
  <p>Привет, {$webguiClient.username}</p>
{:else}
  <p>Ждём данные от мода…</p>
{/if}

Сторы

webguiClient

const webguiClient: Readable<WebGUIClient | null>

Последний снимок клиента (пушится 20 раз/сек). null до первого пуша или вне мода.

<span>{$webguiClient?.username}</span>

webguiEntity

const webguiEntity: Readable<WebGUIEntity | null>

Сущность, по которой игрок кликнул для открытия GUI (через /webgui bind entity), или null, если GUI открыт командой.

webguiSelector

function webguiSelector<T>(
  selector: (client: WebGUIClient) => T,
  equalFn?: (a: T, b: T) => boolean,
): Readable<T | null>

Выводит стор из снимка клиента. Значение меняется только когда меняется выбранное (по equalFn, по умолчанию Object.is), поэтому подписчики не срабатывают на каждый тик.

<script lang="ts">
  import { webguiSelector } from '@webgui/svelte'
  const username = webguiSelector((c) => c.username)
</script>

<span>{$username}</span>

Действия

postToGame

function postToGame(payload: PostToGamePayload): void

Отправляет сообщение в игру через CEF-роутер мода.

postToGame({ channel: 'log', level: 'info', message: 'shop opened' })
postToGame({ channel: 'shop:buy', itemId: 'minecraft:diamond', qty: 1 })

closeGui

function closeGui(): void

Закрывает активный GUI-экран или HUD-оверлей.

runCommand

function runCommand(command: string): void

Выполняет команду от лица игрока — как ввод в чат. Работает только если страница на доверенном origin (trustedCommandOrigins); иначе мод её отклоняет.

<button on:click={() => runCommand('spawn')}>На спавн</button>

webguiToken

function webguiToken(paramName?: string): string | null

Подписанный токен, который мод добавил в URL страницы, или null. Статичен на время жизни страницы. См. Проверка токена.

onWebGUIEvent

function onWebGUIEvent<T = unknown>(
  eventName: string,
  handler: (data: T) => void,
): () => void

Подписка на именованное событие с сервера (WebviewApi.emitToPage). Возвращает функцию отписки — верните её из onMount или вызовите в onDestroy. См. События.

<script lang="ts">
  import { onMount } from 'svelte'
  import { onWebGUIEvent } from '@webgui/svelte'

  let balance = 0
  onMount(() =>
    onWebGUIEvent<{ balance: number }>('walletUpdate', (d) => { balance = d.balance }),
  )
</script>

Утилиты

isInMod() — true, когда есть window.webgui. isReady(client) — true, когда пришёл хотя бы один снимок.

TypeScript

Все типы экспортируются из корня пакета (WebGUIClient, WebGUIEntity, PostToGamePayload, …). Пакет глобально дополняет window.webgui и события webgui:client / webgui:entity — добавьте "types": ["@webgui/svelte"] в tsconfig.json, чтобы обращаться к window.webgui напрямую.