PMServerUI v2

[Azvyl]

What to do in this update:

• Bump version to 2.0.0
• Removed all .idea (JetBrains IDE) project configuration files from version control
• Changed all references of "DavyCraft648" to "Azvyl"
• Changed the use of pocketmine's Translateable to UIRawMessage
• Remove license comment in all file headers
• Added full support for DD-UI
  • CustomForm
  • MessageBox
  • MessageBoxResult
  • Observable
    • setData()
    • getData()
    • getFilteredText() (added in 1.26.20.23)
    • subscribe()
  • UIRawMessage
  • DataDrivenScreenClosedReason (added in 1.26.20.22)
  • PlayerLeftError (added in 1.26.20.22)
  • TextFilteringError (added in 1.26.20.23)
  • FormCloseError (added in 1.26.20.22)
  • ServerShutdownError (added in 1.26.20.22)
• Add usage examples of DDUI
• Test whether the static ui behavior is still the same as v1
• Test whether it works if more than 1 plugin uses the PMServerUI virion or another plugin implements its own DDUI packet sending

Breaking Changes Summary

• All namespaces changed:
  • v1: DavyCraft648\PMServerUI\...
  • v2: Azvyl\PMServerUI\... or Azvyl\PMServerUI\ui\...
• FormDataHandler was removed (replaced by ServerUI architecture + per-form response parsing).
• PMServerUI::register() no longer accepts the optional translation flag (bool $tl).
• Promise::resolve() changed from variadic arguments to a single value.
• FormRejectError no longer extends Error; it now extends RuntimeException.
• Cancel/reject reason enums are now string-backed enums.

Package Metadata Changes

• Composer package:
  • davycraft648/pmserver-ui -> azvyl/pmserver-ui
• Virion antigen:
  • DavyCraft648\PMServerUI -> Azvyl\PMServerUI
• Author:
  • DavyCraft648 -> Azvyl
• Virion version:
  • 1.0.2 -> 2.0.0

Moved Classes / Namespace Replacements

The following classes are conceptually the same, but were moved into the ui namespace:

• ActionFormData -> Azvyl\PMServerUI\ui\ActionFormData
• ActionFormResponse -> Azvyl\PMServerUI\ui\ActionFormResponse
• FormCancelationReason -> Azvyl\PMServerUI\ui\FormCancelationReason
• FormRejectError -> Azvyl\PMServerUI\ui\FormRejectError
• FormRejectReason -> Azvyl\PMServerUI\ui\FormRejectReason
• FormResponse -> Azvyl\PMServerUI\ui\FormResponse
• MessageFormData -> Azvyl\PMServerUI\ui\MessageFormData
• MessageFormResponse -> Azvyl\PMServerUI\ui\MessageFormResponse
• ModalFormData -> Azvyl\PMServerUI\ui\ModalFormData
• ModalFormResponse -> Azvyl\PMServerUI\ui\ModalFormResponse
• UIManager -> Azvyl\PMServerUI\ui\UIManager

Classes that remain in the root namespace (with internal changes):

• PMServerUI -> Azvyl\PMServerUI\PMServerUI
• Promise -> Azvyl\PMServerUI\Promise

Removed / Replaced Classes

• Removed: DavyCraft648\PMServerUI\FormDataHandler
  • Architectural replacements:
    • Azvyl\PMServerUI\ui\ServerUI (form abstraction)
    • Azvyl\PMServerUI\ui\UIManager (tracking + response dispatch)
    • processResponse() implemented per form class (ActionFormData, MessageFormData, ModalFormData)

New Classes in v2

Root

• Azvyl\PMServerUI\UIRawMessage

New UI Layer

• Azvyl\PMServerUI\ui\ServerUI

Data Driven UI (ddui)

• Azvyl\PMServerUI\ddui\DDUI
• Azvyl\PMServerUI\ddui\DDUIManager
• Azvyl\PMServerUI\ddui\CustomForm
• Azvyl\PMServerUI\ddui\CustomFormPayloadComposer
• Azvyl\PMServerUI\ddui\CustomFormRenderContext
• Azvyl\PMServerUI\ddui\DropdownItem
• Azvyl\PMServerUI\ddui\Observable
• Azvyl\PMServerUI\ddui\Subscription
• Azvyl\PMServerUI\ddui\MessageBox (currently placeholder / TODO)

DDUI Elements

• Azvyl\PMServerUI\ddui\elements\CustomFormElement (interface)
• Azvyl\PMServerUI\ddui\elements\ButtonElement
• Azvyl\PMServerUI\ddui\elements\DividerElement
• Azvyl\PMServerUI\ddui\elements\DropdownElement
• Azvyl\PMServerUI\ddui\elements\HeaderElement
• Azvyl\PMServerUI\ddui\elements\LabelElement
• Azvyl\PMServerUI\ddui\elements\SliderElement
• Azvyl\PMServerUI\ddui\elements\SpacerElement
• Azvyl\PMServerUI\ddui\elements\TextFieldElement
• Azvyl\PMServerUI\ddui\elements\ToggleElement

DDUI Packets and Types

• Azvyl\PMServerUI\ddui\packets\ClientboundDataStorePacket
• Azvyl\PMServerUI\ddui\packets\types\DataStorePropertyValue
• Azvyl\PMServerUI\ddui\packets\types\DataStorePropertyType
• Azvyl\PMServerUI\ddui\packets\types\DataStoreChange
• Azvyl\PMServerUI\ddui\packets\types\DataStoreMapEntry
• Azvyl\PMServerUI\ddui\packets\types\BoolDataStorePropertyValue
• Azvyl\PMServerUI\ddui\packets\types\Int64DataStorePropertyValue
• Azvyl\PMServerUI\ddui\packets\types\StringDataStorePropertyValue
• Azvyl\PMServerUI\ddui\packets\types\ListDataStorePropertyValue
• Azvyl\PMServerUI\ddui\packets\types\MapDataStorePropertyValue
• Azvyl\PMServerUI\ddui\packets\types\NoneDataStorePropertyValue

Note:

• The addition of Azvyl\PMServerUI\ddui\packets was made as a compatibility workaround because PocketMine's ClientboundDataStorePacket encoding has parts that are not encoded correctly for this DDUI use case.

Important Method/API Changes

1) Library Bootstrap (PMServerUI)

• v1:
  • register(Plugin $plugin, bool $tl = false): void
  • duplicate register -> throws InvalidArgumentException
• v2:
  • register(Plugin $plugin): void
  • duplicate register -> return (idempotent)
  • added getDDUIManager(): DDUIManager

Impact:

• Code that relied on $tl must migrate to UIRawMessage-based formatting.
• Code that relied on duplicate-register exceptions must be adjusted.

2) Form Sending (show) and Tracking

• v1: form classes hold FormDataHandler; show() sends packets via that handler.
• v2: form classes extend ServerUI; final show() calls PMServerUI::getUIManager()->___send(...).

Impact:

• Internal tracking changed from trackForm(...) to ___track(...) and ___send(...) (internal API).

3) UIManager Response Handling

• v2 adds stricter payload validation:
  • checks player !== null
  • enforces max form response size (10 * 1024 bytes)
  • rejects null form data without cancel reason
• Reject reasons are conceptually the same, but error/enum implementations changed.

Note:

• closeAllForms(Player $player) exists in v2, but is not implemented yet (RuntimeException: Not implemented yet).

4) Static Form Builder API

• Text argument types changed from Translatable|string (v1) to string|UIRawMessage (v2).
• ActionFormData::button():
  • v1: button(..., ?string $iconPath = null, string $iconType = "path")
  • v2: button(..., ?string $iconPath = null, ?string $iconUrl = null)
• ModalFormData:
  • response validation moved from ModalFormResponse::validate(...) to ModalFormData::processResponse(...)
  • compact response handling (nulls for non-interactive controls) is processed directly in processResponse().

5) Response Objects

• Response constructors were simplified:
  • v1 usually accepted (?FormCancelationReason, bool $canceled, ?payload)
  • v2 accepts (?FormCancelationReason, ?payload) and computes canceled automatically ($cancelationReason !== null)
• Static validate(...) methods were removed from ActionFormResponse, MessageFormResponse, and ModalFormResponse.

6) Errors and Enums

• FormRejectError:
  • v1: extends Error
  • v2: extends RuntimeException
• FormCancelationReason and FormRejectReason:
  • v1: unit enums
  • v2: string-backed enums

7) Promise API

• v1: resolve(mixed ...$value) (variadic)
• v2: resolve(mixed $value) (single value, generic template)
• then(...) callbacks in v2 are designed around one resolved value.

New Architecture: Data Driven UI

v2 introduces a DDUI ecosystem that does not exist in v1:

• DDUIManager for lifecycle, observable binding, packet handling, and datastore synchronization.
• Observable + Subscription for reactive server <-> client state.
• CustomForm and DDUI elements for dynamic UI composition.