Forms API

src/pocketmine/Player.php

@@ -68,6 +68,7 @@
 use pocketmine\event\player\PlayerTransferEvent;
 use pocketmine\event\server\DataPacketSendEvent;
 use pocketmine\event\Timings;
+use pocketmine\form\Form;
 use pocketmine\inventory\BigCraftingGrid;
 use pocketmine\inventory\CraftingGrid;
 use pocketmine\inventory\Inventory;
@@ -115,6 +116,7 @@
 use pocketmine\network\mcpe\protocol\LevelSoundEventPacket;
 use pocketmine\network\mcpe\protocol\LoginPacket;
 use pocketmine\network\mcpe\protocol\MobEquipmentPacket;
+use pocketmine\network\mcpe\protocol\ModalFormRequestPacket;
 use pocketmine\network\mcpe\protocol\MovePlayerPacket;
 use pocketmine\network\mcpe\protocol\PlayerActionPacket;
 use pocketmine\network\mcpe\protocol\PlayStatusPacket;
@@ -297,6 +299,15 @@ public static function isValidUserName(?string $name) : bool{
 	 */
 	protected $lastPingMeasure = 1;
 
+	/** @var int */
+	protected $formIdCounter = 0;
+	/** @var int|null */
+	protected $sentFormId = null;
+	/** @var Form|null */
+	protected $sentForm = null;
+	/** @var Form[] */
+	protected $formQueue = [];
+
 	/**
 	 * @return TranslationContainer|string
 	 */
@@ -3229,6 +3240,78 @@ public function sendWhisper(string $sender, string $message){
 		$this->dataPacket($pk);
 	}
 
+	/**
+	 * Sends a Form to the player, or queue to send it if a form is already open.
+	 *
+	 * @param Form $form
+	 * @param bool $prepend if true, the form will be sent immediately after the current form is closed (if any), before other queued forms.
+	 */
+	public function sendForm(Form $form, bool $prepend = false) : void{
+		$form->setInUse();
+
+		if($this->sentForm !== null){
+			if($prepend){
+				array_unshift($this->formQueue, $form);
+			}else{
+				$this->formQueue[] = $form;
+			}
+			return;
+		}
+
+		$this->sendFormRequestPacket($form);
+	}
+
+	/**
+	 * @param int   $formId
+	 * @param mixed $responseData
+	 *
+	 * @return bool
+	 */
+	public function onFormSubmit(int $formId, $responseData) : bool{
+		if($formId !== $this->sentFormId){
+			$this->server->getLogger()->debug("Got unexpected response for form $formId, but waiting for response for $this->sentFormId");
+			return false;
+		}
+
+		$form = null;
+
+		try{
+			$form = $this->sentForm->handleResponse($this, $responseData);
+		}catch(\Throwable $e){
+			$this->server->getLogger()->logException($e);
+		}
+
+		$this->sentFormId = null;
+		$this->sentForm = null;
+
+		try{
+			if($form !== null){
+				$form->setInUse(); //forms in the queue will already be marked as "in use", we only need to check here
+			}else{
+				$form = array_shift($this->formQueue);
+			}
+
+			if($form !== null){
+				$this->sendFormRequestPacket($form);
+			}
+		}catch(\Throwable $e){
+			$this->server->getLogger()->logException($e);
+		}
+
+		return true;
+	}
+
+	private function sendFormRequestPacket(Form $form) : void{
+		$id = $this->formIdCounter++;
+		$pk = new ModalFormRequestPacket();
+		$pk->formId = $id;
+		$pk->formData = json_encode($form);
+		if($this->dataPacket($pk)){
+			$this->sentFormId = $id;
+			$this->sentForm = $form;
+		}
+	}
+
 	/**
 	 * Note for plugin developers: use kick() with the isAdmin
 	 * flag set to kick without the "Kicked by admin" part instead of this method.

src/pocketmine/form/CustomForm.php

@@ -0,0 +1,105 @@
+<?php
+
+/*
+ *
+ *  ____            _        _   __  __ _                  __  __ ____
+ * |  _ \ ___   ___| | _____| |_|  \/  (_)_ __   ___      |  \/  |  _ \
+ * | |_) / _ \ / __| |/ / _ \ __| |\/| | | '_ \ / _ \_____| |\/| | |_) |
+ * |  __/ (_) | (__|   <  __/ |_| |  | | | | | |  __/_____| |  | |  __/
+ * |_|   \___/ \___|_|\_\___|\__|_|  |_|_|_| |_|\___|     |_|  |_|_|
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Lesser General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * @author PocketMine Team
+ * @link http://www.pocketmine.net/
+ *
+ *
+*/
+
+declare(strict_types=1);
+
+namespace pocketmine\form;
+
+use pocketmine\form\element\CustomFormElement;
+use pocketmine\Player;
+use pocketmine\utils\Utils;
+
+abstract class CustomForm extends Form{
+
+	/** @var CustomFormElement[] */
+	private $elements;
+
+	/**
+	 * @param string              $title
+	 * @param CustomFormElement[] $elements
+	 */
+	public function __construct(string $title, array $elements){
+		assert(Utils::validateObjectArray($elements, CustomFormElement::class));
+
+		parent::__construct($title);
+		$this->elements = array_values($elements);
+	}
+
+	/**
+	 * @return string
+	 */
+	public function getType() : string{
+		return Form::TYPE_CUSTOM_FORM;
+	}
+
+	/**
+	 * @param int $index
+	 *
+	 * @return CustomFormElement|null
+	 */
+	public function getElement(int $index) : ?CustomFormElement{
+		return $this->elements[$index] ?? null;
+	}
+
+	/**
+	 * @return CustomFormElement[]
+	 */
+	public function getAllElements() : array{
+		return $this->elements;
+	}
+
+	public function onSubmit(Player $player) : ?Form{
+		return null;
+	}
+
+	/**
+	 * Called when a player closes the form without submitting it.
+	 * @param Player $player
+	 * @return Form|null a form which will be opened immediately (before queued forms) as a response to this form, or null if not applicable.
+	 */
+	public function onClose(Player $player) : ?Form{
+		return null;
+	}
+
+
+	public function handleResponse(Player $player, $data) : ?Form{
+		if($data === null){
+			return $this->onClose($player);
+		}
+
+		if(is_array($data)){
+			/** @var array $data */
+			foreach($data as $index => $value){
+				$this->elements[$index]->setValue($value);
+			}
+
+			return $this->onSubmit($player);
+		}
+
+		throw new \UnexpectedValueException("Expected array or NULL, got " . gettype($data));
+	}
+
+	public function serializeFormData() : array{
+		return [
+			"content" => $this->elements
+		];
+	}
+}

src/pocketmine/form/Form.php

@@ -0,0 +1,133 @@
+<?php
+
+/*
+ *
+ *  ____            _        _   __  __ _                  __  __ ____
+ * |  _ \ ___   ___| | _____| |_|  \/  (_)_ __   ___      |  \/  |  _ \
+ * | |_) / _ \ / __| |/ / _ \ __| |\/| | | '_ \ / _ \_____| |\/| | |_) |
+ * |  __/ (_) | (__|   <  __/ |_| |  | | | | | |  __/_____| |  | |  __/
+ * |_|   \___/ \___|_|\_\___|\__|_|  |_|_|_| |_|\___|     |_|  |_|_|
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Lesser General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * @author PocketMine Team
+ * @link http://www.pocketmine.net/
+ *
+ *
+*/
+
+declare(strict_types=1);
+
+/**
+ * API for Minecraft: Bedrock custom UI (forms)
+ */
+namespace pocketmine\form;
+
+use pocketmine\Player;
+
+/**
+ * Base class for a custom form. Forms are serialized to JSON data to be sent to clients.
+ */
+abstract class Form implements \JsonSerializable{
+
+	public const TYPE_MODAL = "modal";
+	public const TYPE_MENU = "form";
+	public const TYPE_CUSTOM_FORM = "custom_form";
+
+	/** @var string */
+	protected $title = "";
+	/** @var bool */
+	private $inUse = false;
+
+	public function __construct(string $title){
+		$this->title = $title;
+	}
+
+	/**
+	 * Returns the type used to show this form to clients
+	 * @return string
+	 */
+	abstract public function getType() : string;
+
+	/**
+	 * Returns the text shown on the form title-bar.
+	 * @return string
+	 */
+	public function getTitle() : string{
+		return $this->title;
+	}
+
+	/**
+	 * Handles a form response from a player. Plugins should not override this method, override {@link onSubmit}
+	 * instead.
+	 *
+	 * @param Player $player
+	 * @param mixed  $data
+	 *
+	 * @return Form|null a form which will be opened immediately (before queued forms) as a response to this form, or null if not applicable.
+	 */
+	abstract public function handleResponse(Player $player, $data) : ?Form;
+
+	/**
+	 * Called when a player submits this form. Each form type usually has its own methods for getting relevant data from
+	 * them.
+	 *
+	 * Plugins should extend the class and override this function and add their own code to handle form responses as
+	 * they wish.
+	 *
+	 * @param Player $player
+	 * @return Form|null a form which will be opened immediately (before queued forms) as a response to this form, or null if not applicable.
+	 */
+	abstract public function onSubmit(Player $player) : ?Form;
+
+	/**
+	 * Returns whether the form has already been sent to a player or not. Note that you cannot send the form again if
+	 * this is true.
+	 *
+	 * @return bool
+	 */
+	public function isInUse() : bool{
+		return $this->inUse;
+	}
+
+	/**
+	 * Called to flag the form as having been sent to prevent it being used again, to avoid concurrency issues.
+	 */
+	public function setInUse() : void{
+		if($this->isInUse()){
+			throw new \InvalidArgumentException("Form is already in use, create a new one instead");
+		}
+		$this->inUse = true;
+	}
+
+	/**
+	 * Clears response data from a form, useful if you want to reuse the same form object several times.
+	 */
+	public function clearResponseData() : void{
+
+	}
+
+	/**
+	 * Serializes the form to JSON for sending to clients.
+	 *
+	 * @return array
+	 */
+	final public function jsonSerialize() : array{
+		$jsonBase = [
+			"type" => $this->getType(),
+			"title" => $this->getTitle()
+		];
+
+		return array_merge($jsonBase, $this->serializeFormData());
+	}
+
+	/**
+	 * Serializes additional data needed to show this form to clients.
+	 * @return array
+	 */
+	abstract protected function serializeFormData() : array;
+
+}