EN

← Runtime

Tutorial — Runtime

1. Install the extension

In your project, add the extension to your game:

bin/jumphp extension:add <game> jumphp/runtime

The engine finds it by itself at startup, nothing to wire.

2. The runtime badge in each state: green, orange, red, grey

Create a scene in src/Extensions/ (or copy it with extension:add) and read the code below: the comments say what to press.

<?php

namespace App\Extensions\Runtime;

use JumPHP\Gui\Form;
use JumPHP\Net\RuntimeLink;
use JumPHP\Runtime\ManualRuntime;
use JumPHP\Runtime\RuntimeBadge;

/**
 * Sample of the extension: the status badge of the JumPHP runtime, in its five looks. Here a runtime you drive by hand (a click on
 * "Next state"), the real application uses `$engine->runtime()` and the badge finds it by itself.
 * Click the badge: orange asks for the authorisation (it turns green), red opens the guide.
 * JUMPHP_SCENE='App\Extensions\Runtime\BadgeSample' bin/jumphp run runtime-demo
 */
final class BadgeSample extends Form
{
    public const LABEL = 'The runtime badge in each state: green, orange, red, grey';

    private const STATES = [RuntimeLink::READY, RuntimeLink::RUNNING, RuntimeLink::MISSING, RuntimeLink::UNSUPPORTED, RuntimeLink::CHECKING];
    private int $at = 2;
    private ManualRuntime $fake;

    public function enter(array $params = []): void
    {
        $this->fake = new ManualRuntime(self::STATES[$this->at]);
        $this->build(['layout' => 'column', 'padding' => 24, 'gap' => 14, 'children' => [
            ['type' => 'label', 'text' => 'The runtime badge', 'style' => 'title'],
            ['type' => 'label', 'style' => 'muted', 'text' => 'Put it next to the connection fields of your app. It looks for the runtime by itself.'],
            ['class' => RuntimeBadge::class, 'id' => 'badge'],
            ['type' => 'button', 'id' => 'next', 'text' => 'Next state', 'events' => ['click' => 'onNext']],
            ['type' => 'label', 'id' => 'state', 'text' => ''],
        ]]);
        $this->widget('badge')->setRuntime($this->fake);
        $this->show();
    }

    public function onNext(mixed $sender = null): void
    {
        $this->at = ($this->at + 1) % count(self::STATES);
        $this->fake->setState(self::STATES[$this->at]);
        $this->show();
    }

    private function show(): void
    {
        $this->widget('state')->text = 'State: ' . $this->fake->state();
    }
}

Run it:

JUMPHP_SCENE='App\Extensions\Runtime\BadgeSample' bin/jumphp run <game>

3. The install guide: download, install, start, allow, then it turns green by itself

Create a scene in src/Extensions/ (or copy it with extension:add) and read the code below: the comments say what to press.

<?php

namespace App\Extensions\Runtime;

use JumPHP\Gui\Form;
use JumPHP\Net\RuntimeLink;
use JumPHP\Runtime\ManualRuntime;
use JumPHP\Runtime\RuntimeGuide;

/**
 * Sample of the extension: the install guide (RuntimeGuide), a dialog with the four steps. Here "the user" is you: "Pretend it is
 * installed and started" moves the fake runtime on, and the guide (which looks again every 2 seconds) turns green by itself.
 * JUMPHP_SCENE='App\Extensions\Runtime\GuideSample' bin/jumphp run runtime-demo
 */
final class GuideSample extends Form
{
    public const LABEL = 'The install guide: download, install, start, allow, then it turns green by itself';

    private ManualRuntime $fake;

    public function __construct(private RuntimeGuide $guide)
    {
        parent::__construct();
    }

    public function enter(array $params = []): void
    {
        $this->fake = new ManualRuntime(RuntimeLink::MISSING);
        $this->build(['layout' => 'column', 'padding' => 24, 'gap' => 14, 'children' => [
            ['type' => 'label', 'text' => 'The install guide', 'style' => 'title'],
            ['type' => 'button', 'id' => 'open', 'text' => 'Open the guide', 'style' => 'primary', 'events' => ['click' => 'onOpen']],
            ['type' => 'button', 'id' => 'started', 'text' => 'Pretend it is installed and started', 'events' => ['click' => 'onStarted']],
            ['type' => 'label', 'id' => 'note', 'style' => 'muted', 'text' => 'A real app opens it from a red badge, or with scenes->push(RuntimeGuide::class).'],
        ]]);
        $this->guide->setRuntime($this->fake);
    }

    public function onOpen(mixed $sender = null): void
    {
        $this->scenes()->push($this->guide);
    }

    public function onStarted(mixed $sender = null): void
    {
        $this->fake->setState(RuntimeLink::RUNNING);
    }
}

Run it:

JUMPHP_SCENE='App\Extensions\Runtime\GuideSample' bin/jumphp run <game>

4. Space changes the runtime state: what auto, server and local connect to

Create a scene in src/Extensions/ (or copy it with extension:add) and read the code below: the comments say what to press.

<?php

namespace App\Extensions\Runtime;

use JumPHP\Net\BridgeRoute;
use JumPHP\Net\RuntimeLink;
use JumPHP\Renderer\Renderer;
use JumPHP\Runtime\ManualRuntime;
use JumPHP\Scene\AbstractScene;

/**
 * Sample of the extension: which bridge a browser connection opens in each net_mode, for the runtime's state. Space changes the state
 * (fake runtime). In your project.yaml: `net_mode: auto | server | local` (or ?net_mode= in the page URL, env JUMPHP_NET_MODE).
 * JUMPHP_SCENE='App\Extensions\Runtime\NetModeSample' bin/jumphp run runtime-demo
 */
final class NetModeSample extends AbstractScene
{
    public const LABEL = 'Space changes the runtime state: what auto, server and local connect to';

    private const SERVER = 'wss://tcp.jumphp.net/ws';
    private const STATES = [RuntimeLink::MISSING, RuntimeLink::RUNNING, RuntimeLink::READY];
    private int $at = 0;
    private ManualRuntime $runtime;

    public function enter(array $params = []): void
    {
        $this->runtime = new ManualRuntime(self::STATES[$this->at]);
    }

    public function update(float $dt): void
    {
        if ($this->actions()->isPressed('confirm') || $this->engine->input->getMouse()->isPressed(1)) {
            $this->at = ($this->at + 1) % count(self::STATES);
            $this->runtime->setState(self::STATES[$this->at]);
        }
    }

    public function render(Renderer $r): void
    {
        $r->clear([16, 18, 30]);
        $font = $this->font();
        $x = 16;
        $font->draw($r, 'RUNTIME STATE: ' . strtoupper($this->runtime->state()), $x, 14, 1, [255, 220, 120]);
        $font->draw($r, 'PRESS SPACE OR CLICK TO CHANGE IT', $x, 28, 1, [140, 150, 190]);
        foreach (['auto', 'server', 'local'] as $i => $mode) {
            try {
                $where = BridgeRoute::resolve($mode, $this->runtime, self::SERVER);
                $color = $where === self::SERVER ? [150, 170, 220] : [120, 230, 150];
            } catch (\RuntimeException $e) {
                $where = 'ERROR: runtime not available (' . $this->runtime->state() . ')';
                $color = [240, 110, 110];
            }
            $font->draw($r, strtoupper($mode), $x, 56 + $i * 30, 1, [255, 255, 255]);
            $font->draw($r, $where, $x + 60, 56 + $i * 30, 1, $color);
        }
    }
}

Run it:

JUMPHP_SCENE='App\Extensions\Runtime\NetModeSample' bin/jumphp run <game>

5. Check

bin/jumphp test <game>
bin/jumphp shot <game>

Runtime Documentation