README

Framework-agnostic PHP library for OpenSimulator grid management

⚠️ Important Notice

This is a pure PHP library - it does nothing by itself!

The OpenSimulator Engine provides core functionality for managing OpenSim grids, but requires a parent application to function. It handles database operations, configuration management, and OpenSim protocol communication, but provides no user interface or web endpoints.

Quick Start for grid/simulator admin

Don't install this directly! Instead, choose a complete solution:

• OpenSim CLI - Command-line tools to install and manage your grid or standalone simulator. Includes this engine, web helpers and admin tools.
• W4OS WordPress Plugin - Complete WordPress integration for OpenSim grids. Best for: Complete integration in a WordPress website.
• OpenSim Helpers - Provides mainly helpers/ required by OpenSim grids to function properly, as well as minimal webui features. Best for: Separate helpers management, with minimal integration with the website.

Project History

This library consolidates over a decade of OpenSimulator integration work that was previously scattered across multiple projects. While the dedicated engine repository is recent, the functionality has evolved through years of real-world usage in production OpenSim grids.

The code has been battle-tested across different implementations before being organized into this reusable, framework-agnostic library.

What This Library Does

• ✅ The models of a grid - grids, simulators, services, avatars, regions, parcels, estates: listed, found, changed, the same way (docs/data.md)
• ✅ The controllers - Robust and OpenSim processes: start, stop, restart, status, console
• ✅ Configuration - the ini files read as OpenSimulator reads them, written without losing what the person added
• ✅ Databases - every database asked as itself, wherever the grid keeps it (MySQL, MariaDB)
• ✅ Provisioning - planners and provisioners that make a grid, a simulator, a region
• ✅ Scheduling - tasks that run by cron or by pseudo cron, locked, with their last run kept
• ✅ A contract - resources as JSON:API documents, errors as RFC 9457 problems, an OpenAPI document checked against the models
• ✅ Security functions, forms, archives (OAR, IAR), health checks

What This Library Does NOT Do

• ❌ No web interface or HTML pages
• ❌ No user HTTP request handling
• ❌ No user authentication
• ❌ No WordPress or other CMS/framework dependencies

For Developers:

• Use this engine to build your own OpenSim management applications
• Integrate OpenSim functionality into existing PHP projects
• Create custom grid administration tools

Requirements

• PHP 8.2 or newer
• PHP extensions curl, filter, intl, json, mbstring, mysqli, pdo, session, simplexml, gettext: sudo apt install php-cli php-curl php-intl php-mbstring php-mysql php-xml
• optional PHP xmlrpc extension (engine provides properly maintained replacement functions)

Fully tested on:

• Ubuntu 24.04 and 26.04
• Debian 12 and 13
• macOS 13.7.8 and later

The machine and its models

Everything the engine does on a machine goes through an Environment: where the install is (Layout), its processes, its launcher, its consoles, its clock. A front-end makes one, a test makes one with fakes.

use OpenSim\Config\Layout;
use OpenSim\Models\{Grid, Simulator, Service};
use OpenSim\Runtime\Environment;

$environment = Environment::system(Layout::resolve());      // the install of this machine
$grid = Grid::find($environment, 'vonda');
$grid->robust()->isRunning();                                // its Robust (a controller)
$grid->service('asset')->url();                              // a service of the grid, and who serves it
$simulator = $grid->simulator('welcome');
$simulator->service('profile')->url();                       // the service as this simulator reaches it
$grid->start(simulators: true);

A grid has one or several Robust instances, each serving some of its services; a standalone grid has none, its simulator serves everything. The simulators inherit the services of their grid.

OpenSim\Testing\Machine is a machine that is a folder (a grid demo, two simulators), EnvironmentFake::with($layout) an environment that touches nothing: the suite runs anywhere (composer test).

Developer Installation

As Composer Package

composer require magicoli/opensim-engine

As Git Submodule

git submodule add https://github.com/magicoli/opensim-engine.git engine

Usage in Code

require 'vendor/autoload.php';   // PSR-4: OpenSim\ is src/; the gettext stand-in and the xmlrpc polyfill load by themselves

On the command line

bin/opensim-api (vendor/bin/opensim-api for a project that has the engine) is the API on the command line, for the tools that are not PHP: opensim-api GET /forms/grid, opensim-api --grid=demo GET /monitor format=text. The install is the one of opensim.conf or of the OPENSIM_* variables. The script first reads the .env of the engine and ~/.opensimrc (lib/rc-helpers, read_rc, for any script to source): bash files, run as they are, e.g. to set the PATH so that it is the php you want that runs.

OpenSim\Container\Podman manages Podman containers without a shell. Pass a connection explicitly when targeting a remote Podman service; bin/opensim-container.php is the command-line adapter for Bash callers (vendor/bin/opensim-container.php when installed as a Composer dependency). Container integration tests are opt-in with PODMAN_INTEGRATION=1; CONTAINER_CONNECTION selects the Podman connection and PODMAN_TEST_IMAGE can select the test image.

Documentation

• Developer Guide - Architecture rules and patterns
• The data of a grid - the models (avatars, regions, parcels), the collections and the databases
• The API - the resources, their attributes and what can be written, from the contract (docs/api/openapi.yaml); composer docs makes it again, the descriptions are written in src/Api/Contract.php
• Migration of the consumers - what was renamed, moved or removed

Contributing

This library follows strict architectural principles:

• Framework-agnostic (no WordPress, no Laravel, etc.)
• Pure data processing (no HTTP input/output)
• Explicit data passing (no global variables)

See DEVELOPERS.md for complete guidelines.

License

AGPLv3 - See LICENSE file for details.

Support

• End Users: Get support from the parent project using this engine (W4OS, Helpers)
• Developers: Create issues for bugs or feature requests https://github.com/magicoli/opensim-engine/issues
• Documentation: Check the parent project documentation first