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.

Namespace	What it is
`OpenSim\Models`	`Grid`, `Simulator`, `Service` (of the machine), `Avatar`, `Region`, `Parcel`, `Estate` (of a grid's databases)
`OpenSim\Controllers`	`RobustController`, `OpenSimController`: the processes that serve
`OpenSim\Runtime`	`Environment`, `Core` (an OpenSimulator release), the process table, the launcher
`OpenSim\Config`	`Layout` (opensim.conf), `GridConfig` (the files of a grid), `ConfigReader`, `IniEditor`
`OpenSim\Data`	`Database` (the databases of a grid), `Connections`, `OSPDO`, `Collection`
`OpenSim\Provisioning`	planners and provisioners: they answer "what would this be" before "make it"
`OpenSim\Scheduling`	`Scheduler`, `Task`: cron and pseudo cron
`OpenSim\Api`	`Api`, `Contract`, `Problem`, `Handler`: the resources as JSON:API, the errors as RFC 9457, served as a PSR-15 handler; `Formats` and `Endpoints` describe what OpenSimulator and the viewers call; `Legacy` gives the old scripts the standard
`OpenSim\Services`	the services the helpers serve: the search (`SearchQuery`, `SearchRegistry`, `SearchParser`, `EventsParser`), the offline messages, the currency and the land tools, XML-RPC
`OpenSim\Archives`, `Health`, `Hypergrid`, `Network`, `Security`, `Forms`, `Testing`	archives, health checks, hypergrid links, ports, escaping, forms, fakes

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

magicoli / opensim-engine

Package info

Security

Statistics