Display Names: installation, architecture and troubleshooting
Complete guide to Firestorm-compatible Display Names for OpenSimulator 0.9.3.x.
Download the Display Names module
Official precompiled ZIP for OpenSimulator 0.9.3.1, release v1.0.0. For another revision, compile the addon against the matching server source.
Download ZIP — OpenSimulator 0.9.3.1
View official release · Browse precompiled files · Module source code
The PHP/MySQL backend is separate: also obtain the source repository for web/displayname/ and database/displaynames.sql, then follow the full installation guide.
Purpose and compatibility
Display Names is an unofficial community module enabling Firestorm-compatible display names on OpenSimulator 0.9.3.x. A precompiled DLL is validated for 0.9.3.1; for other revisions, compile against the exact server source tree. Display names do not replace login usernames.
Architecture: shared backend and per-simulator module
The system uses a grid-wide HTTPS PHP/MySQL backend and a module on every simulator that needs Display Names CAPS. Updates can be broadcast to nearby viewers. Remote Hypergrid UUIDs unknown locally should fall back to legacy name handling rather than being fabricated as local accounts.
Prerequisites and supplied files
Prepare HTTPS, PHP with PDO MySQL, a MySQL database and backend read access to ROBUST UserAccounts. The 0.9.3.1 precompiled package includes the DLL, PDB and Mono.Addins manifest. Back up older versions and stop the simulator before replacing binaries.
Adapt the example: do not reuse paths or credentials without verification.
precompiled/OpenSimulator-0.9.3.1/DisplayNameSimModule.dll precompiled/OpenSimulator-0.9.3.1/DisplayNameSimModule.pdb precompiled/OpenSimulator-0.9.3.1/DisplayNameSimModule.addin.xml # À copier dans bin/ du simulateur concerné
Create the Display Names database
Create a dedicated database and import the module repository's database/displaynames.sql into it. The schema creates display_names (name and next permitted change) and display_name_history (set/reset audit history). Do not confuse this database with ROBUST.
Adapt the example: do not reuse paths or credentials without verification.
CREATE DATABASE opensim_displaynames CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci; -- Ensuite importer database/displaynames.sql dans cette base.
Required SQL privileges
The installation guide requires SELECT on robust.UserAccounts to resolve legacy names, and SELECT/INSERT/UPDATE/DELETE on the Display Names database. Adapt database names, allowed MySQL client hostname and secret. Avoid root and never expose MySQL to the public Internet.
Adapt the example: do not reuse paths or credentials without verification.
CREATE USER 'displaynames_user'@'localhost' IDENTIFIED BY 'SECRET_A_CHANGER'; GRANT SELECT ON `robust`.`UserAccounts` TO 'displaynames_user'@'localhost'; GRANT SELECT, INSERT, UPDATE, DELETE ON `opensim_displaynames`.* TO 'displaynames_user'@'localhost';
Install and configure the PHP service
Copy web/displayname/ from the module repository to an HTTPS-served directory. Copy config/config.php.example to config/config.php, then set db_host, db_port, db_user, db_pass, db_displaynames and db_robust. Never commit real config.php or allow web access to credentials/logs. ServiceBase points to the service directory, not /get.
Adapt the example: do not reuse paths or credentials without verification.
'db_host' => '127.0.0.1', 'db_port' => 3306, 'db_user' => 'displaynames_user', 'db_pass' => 'SECRET_A_CHANGER', 'db_displaynames' => 'opensim_displaynames', 'db_robust' => 'robust', 'change_delay_days' => 7,
Security warning for /set and /reset
The repository example uses allow_all_ips=true for remote simulators. In the current backend this allows write requests without IP restrictions; it is NOT authentication. A publicly exposed installation could allow unauthorized name changes through its endpoints. Add robust backend authentication and/or appropriately enforced network controls before opening to untrusted traffic; setting the option false may block all writes rather than provide an allowlist.
Test endpoints before enabling the module
Test GET /get with a local UUID on the final HTTPS URL; it should return JSON. Expected routes are GET /get, POST /set and POST /reset. For 404 check .htaccess, mod_rewrite/AllowOverride and directory location. Avoid HTTP 301/302 redirects for POST requests.
Adapt the example: do not reuse paths or credentials without verification.
curl -i 'https://grid.example/displayname/get?id=UUID_LOCAL'
Configure [DisplayNameCaps] in OpenSim.ini
Add this block as a separate section in the active OpenSim.ini. ServiceBase must not include /get, /set, /reset or /index.php. Other parameters control HTTP timeout, cache TTL, maximum concurrent calls and verbose logging.
Adapt the example: do not reuse paths or credentials without verification.
[DisplayNameCaps] ServiceBase = "https://grid.example/displayname" HttpTimeoutMs = 5000 CacheTtlMinutes = 30 MaxConcurrentServiceCalls = 5 Verbose = true
Enable the module in [Modules]
In the active GridCommon.ini, locate its existing [Modules] section and add DisplayNameCapsModule to SharedRegionModules. Preserve all existing shared modules and do not duplicate the SharedRegionModules setting. Actual include files depend on the deployment.
Adapt the example: do not reuse paths or credentials without verification.
[Modules] SharedRegionModules = "DisplayNameCapsModule" # Exemple si aucune autre valeur n’existe déjà.
Build for a different OpenSimulator revision
For an OpenSimulator 0.9.3.x revision different from the precompiled build, copy source/DisplayNameSimModule into addon-modules/DisplayNameSimModule of the matching OpenSimulator source tree, run prebuild and compile the Release solution. Verify generated DLL and addin manifest. This module runs in region simulators, not in ROBUST.
Adapt the example: do not reuse paths or credentials without verification.
# Linux (à la racine du code source OpenSimulator) : ./runprebuild.sh dotnet build OpenSim.sln --configuration Release # Windows : runprebuild.bat puis dotnet build OpenSim.sln --configuration Release
Verify module loading and initial Firestorm login
After restart search OpenSim.log for Plugin Loaded: DisplayNameSimModule and [DisplayNameCaps]: MODULE LOADED; the shared module should load once, not twice. If Mono.Addins fails discovery, stop the simulator and back up/rename addin-db-004 only when present. An initial Firestorm cache clear and complete viewer restart may be needed after first enabling Display Names.
Adapt the example: do not reuse paths or credentials without verification.
grep -nEi 'DisplayNameCaps|DisplayNameSimModule|ERROR|exception' /chemin/vers/OpenSim.log | tail -n 100
Test end-to-end behavior
Test: name above avatar and in profile, availability of legacy username, change, reset, updates observed by a second viewer, then Hypergrid contact behavior. Repeat on each enabled simulator; one region's successful test does not prove every simulator works.
Log-first troubleshooting
If Firestorm controls are disabled, confirm CAPS in OpenSim.log before clearing viewer cache. For 404 check Apache rewrite and ServiceBase. If backend saved a change but viewer reports failure check HTTP status and CAPS response. If reset does not refresh nearby viewers inspect DisplayNameUpdate and EventQueue. Remote Hypergrid UUIDs not found locally may be expected; correlate logs before diagnosing failure.
Adapt the example: do not reuse paths or credentials without verification.
# Simulateur : grep -nEi 'DisplayNameCaps|DisplayNameSimModule|exception|ERROR' /chemin/vers/OpenSim.log | tail -n 120 # Web PHP/Apache : consulter le journal d’erreurs réel du vhost # Backend, seulement si debug=true et droits de fichiers adaptés : tail -n 100 /chemin/vers/displayname/logs/displaynames.log
Backup, history and operations
Back up display_names and display_name_history alongside ROBUST accounts and backend configuration. The change_delay_days restriction is enforced by the backend: 0 means no delay, 7 means seven days. Debug logs may include personal data and IPs; restrict access and retention, and disable unnecessary debugging in production.