Prefab Files

Prefab files use the .prefab.php extension and return one object definition in the same general shape used by a scene hierarchy item.

Naming Convention

<name>.prefab.php

Example:

bullet.prefab.php

Basic Example

<?php

use Sendama\Engine\Core\GameObject;
use Sendama\Engine\Physics\Rigidbody;

return [
    'type' => GameObject::class,
    'name' => 'Bullet',
    'tag' => 'Bullet',
    'position' => ['x' => 0, 'y' => 0],
    'rotation' => ['x' => 0, 'y' => 0],
    'scale' => ['x' => 1, 'y' => 1],
    'components' => [
        [
            'class' => Rigidbody::class,
            'data' => [
                'mass' => 1,
                'useGravity' => false,
                'isTrigger' => true,
            ],
        ],
    ],
    'sprite' => [
        'texture' => [
            'path' => 'Textures/bullet.texture',
            'position' => ['x' => 0, 'y' => 1],
            'size' => ['x' => 1, 'y' => 1],
        ],
    ],
];

Schema

A prefab supports the same major fields as a scene hierarchy object:

• type
• name
• tag
• position
• rotation
• scale
• sprite
• components
• children
• UI fields such as size and text when the prefab targets a UI element

What Prefabs Are For

Use prefabs for:

• reusable scene content
• runtime spawning
• object pooling
• keeping scene files smaller

Good prefab candidates include:

• bullets
• enemies
• pickups
• weapons
• UI widgets reused across multiple scenes

Runtime Loading

The engine can load prefab metadata into a live GameObject.

Common usage patterns:

• assign a prefab path in scene or prefab component metadata
• expose a GameObject-typed serialized field and let the runtime hydrate it
• instantiate or clone the resulting object at runtime

The scene manager resolves prefab references from:

• absolute paths
• asset-relative paths such as Prefabs/bullet.prefab.php
• extensionless forms where .prefab.php can be inferred

Editor Behavior

In the editor:

• prefabs can be created from the asset create menu
• scene objects can be exported directly as prefabs
• prefab fields can be edited in the inspector
• prefab changes are written immediately

Design Advice

Keep prefab data declarative. Put behavior in scripts and use prefab metadata to configure that behavior.