SceneManager

SceneManager is the PHP API you use when a script needs to work with the current scene or move the player to another scene.

The most common workflow is:

  1. Create the scenes in the editor.
  2. Open Build Settings and add the scenes you want the game to load.
  3. Make sure the scene is enabled in the Build Settings scene list.
  4. Put your PHP code in a Behaviour attached to a normal GameObject.
  5. Call SceneManager::loadScene('SceneName') from that behaviour.

The load request is applied by the engine at a safe point in the frame, after script update work has finished. That keeps the current scene from being destroyed in the middle of a callback.

Namespace:

namespace Lenga\Engine\SceneManagement;

Import:

use Lenga\Engine\SceneManagement\SceneManager;

getActiveScene

Returns the scene that is running, or null if there is no active scene.

public static function getActiveScene(): ?Scene

Use this when you need to find objects, canvases, or other scene-owned content from a script.

$scene = SceneManager::getActiveScene();

if ($scene === null) {
    Debug::warn('There is no active scene yet.');
    return;
}

loadScene

Requests a scene transition.

public static function loadScene(string $sceneNameOrPath): void

Use the scene name when possible:

SceneManager::loadScene('Level1');

For that to work, Level1 should be present and enabled in Build Settings. Lenga can also accept a project-relative scene path when you need to be explicit:

SceneManager::loadScene('Assets/Scenes/Level1.scene.json');

If the scene cannot be found, is disabled, or fails validation, loadScene throws a RuntimeException.

tryLoadScene

Requests a scene transition and returns whether the request was accepted.

public static function tryLoadScene(string $sceneNameOrPath): bool

Use this when a missing scene should be handled gracefully instead of throwing:

if (!SceneManager::tryLoadScene('Level1')) {
    Debug::warn('Could not load Level1. Check Build Settings.');
}

loadSceneByPath

Requests a scene transition by path.

public static function loadSceneByPath(string $scenePath): void

This is a readability wrapper around loadScene. It is useful when you want the code to make it obvious that the value is a path:

SceneManager::loadSceneByPath('Assets/Scenes/MainMenu.scene.json');

instantiatePrefab

Creates an instance of a prefab in the active scene.

public static function instantiatePrefab(string $assetPath, ?string $name = null): GameObject
$coin = SceneManager::instantiatePrefab('Assets/Prefabs/Coin.prefab.json', 'Coin Pickup');

assetPath should be a project-relative path.

createScene

public static function createScene(string $name): Scene

Runtime scene creation is not supported yet. Use the editor to create scenes, then load them by name or project-relative path.

setActiveScene

public static function setActiveScene(Scene $scene): void

Directly swapping the active scene object is not supported yet. Use loadScene or tryLoadScene for runtime scene transitions.

Example

This example belongs in a Behaviour class attached to a normal GameObject, such as a MainMenuController object in your menu scene.

<?php

declare(strict_types=1);

namespace MyGame\Scripts;

use Lenga\Engine\Core\Behaviour;
use Lenga\Engine\Core\Debug;
use Lenga\Engine\SceneManagement\SceneManager;

final class MainMenuController extends Behaviour
{
    public function startGame(): void
    {
        SceneManager::loadScene('Level1');
    }

    public function tryOpenBonusLevel(): void
    {
        if (!SceneManager::tryLoadScene('BonusLevel')) {
            Debug::warn('BonusLevel could not be loaded.');
        }
    }
}

You can call these methods from your own button-handling code. The important part is that the script lives on a GameObject in the running scene, because behaviours are how Lenga runs gameplay PHP code.