OpenSimulator performance: diagnostics and optimization
Technical guide: statistics, simulation timing, CPU, RAM, physics, scripts, assets, networking and troubleshooting.
Method: diagnose before tuning
1. Define the symptom
Separate avatar movement lag, viewer rendering, asset loading, scripts, teleports and physics issues. Record time, region, avatar count, version and when it occurs.
2. Measure before and after
Measure at rest and during representative activity. Keep the same scene, avatar count and observation period. One measurement alone cannot explain the root cause.
3. Change gradually
Back up INI files, change one setting at a time, review logs, and roll back when the benefit is not measurable. Do not blindly apply advice from other versions.
OpenSimulator statistics: reading and interpreting
Actual console commands
StatsManager.cs registers stats show and the show stats alias. With no argument, it displays legacy region statistics where available. list shows categories; all shows registered statistics.
Example command or setting: verify before use.
stats show stats show list stats show all show stats
Statistics visible in the viewer
On many viewers, Ctrl+Shift+1 opens statistics. Viewer FPS is not the same as simulator performance. Also inspect ping, packet loss, Physics Time and Script Time where supported.
Sim FPS and Physics FPS
Do not always expect a literal 55 simulation FPS. The source documents Normalized55FPS and normalization for viewers. Expected readings depend on simulation timing; prioritize stability and execution times.
Physics Time
High physics time during collisions or movement suggests physical objects, collision meshes, vehicles or object counts. Physics FPS alone may hide rising cost until saturation.
Script Time and event queues
High script time deserves separate analysis from frame rendering. Script engines can process events asynchronously. Many timers and listeners may overload a process even when each script seems lightweight.
Stats URI and network exposure
OpenSimDefaults.ini defines Stats_URI = jsonSimStats and a ManagedStatsRemoteFetchURI option. Protect these endpoints by network policy; do not automatically expose monitoring endpoints publicly.
Example command or setting: verify before use.
[Startup] Stats_URI = "jsonSimStats" ; ManagedStatsRemoteFetchURI = "ManagedStats"
Linux CPU, RAM, swap and storage
Find resource-heavy processes
top and ps show per-process CPU and memory. With multiple simulator processes, compare PIDs: one simulator can be saturated even if host average CPU is low.
Example command or setting: verify before use.
top ps -eo pid,%cpu,rss,cmd --sort=-%cpu | head -n 20
Understand vmstat
r is runnable work; si/so are swap-in and swap-out; wa is I/O wait; st is hypervisor CPU steal. Interpret sustained values in the context of reported lag.
Example command or setting: verify before use.
vmstat 1 10
Cached memory is not a leak
Linux filesystem cache consumes RAM to speed up I/O. available is often more useful than free for assessing spare memory. High RSS alone is not proof of a leak without persistent abnormal growth.
Example command or setting: verify before use.
free -h ps -eo pid,rss,%mem,cmd --sort=-rss | head -n 20
Inspect one process and its threads
top -H -p PID helps reveal whether one thread is consuming a core. Providing many CPU cores does not mean that one task automatically uses them all.
Example command or setting: verify before use.
top -H -p PID
Disk and latency
Long disk waits can slow databases, caches and OAR backups. Measure latency and free space; do not confuse high throughput with high latency.
Example command or setting: verify before use.
df -h vmstat 1 10
Virtualization and shared resources
In a VM, persistent st in vmstat means time lost to the hypervisor. vCPU overcommit or host memory pressure may cause lag even with correct simulator settings.
Region frame pacing and scheduling
FrameTime — advanced timing setting
Your fork's OpenSimDefaults.ini uses FrameTime = 0.0909 seconds (about 11 iterations per second). Lowering it may increase update frequency and CPU/network load. The source advises not going below the physics engine step time.
Example command or setting: verify before use.
[Startup] FrameTime = 0.0909
UpdateObjectsEveryNFrames
Reference value 1: interval for scheduled object updates. Increasing it may delay object updates; it is not a generic lag fix.
Example command or setting: verify before use.
[Startup] UpdateObjectsEveryNFrames = 1
UpdateAgentsEveryNFrames
Reference value 1: frequency of selected agent position and velocity updates. Raising it too far may impair movement smoothness.
Example command or setting: verify before use.
[Startup] UpdateAgentsEveryNFrames = 1
UpdatePhysicsEveryNFrames
Reference value 1: physics execution or synchronization interval depending on engine. Source comments recommend keeping it at 1 in normal use.
Example command or setting: verify before use.
[Startup] UpdatePhysicsEveryNFrames = 1
UpdateEventsEveryNFrames
Reference value 1. Source comments indicate this should probably never differ from 1, as it schedules frame events delivered to modules.
Example command or setting: verify before use.
[Startup] UpdateEventsEveryNFrames = 1
UpdateCoarseLocationsEveryNFrames
Reference value 50: coarse location updates used by features such as the minimap. The interval is expressed in frames, so it depends on FrameTime.
Example command or setting: verify before use.
[Startup] UpdateCoarseLocationsEveryNFrames = 50
UpdateTerrainEveryNFrames
Reference value 50: terrain update scheduling to viewers. Changing it without measurement can delay visible changes or affect network traffic.
Example command or setting: verify before use.
[Startup] UpdateTerrainEveryNFrames = 50
UpdateStorageEveryNFrames
Reference value 200: periodic object persistence processing subject to persistence timing. Behavior also depends on MinimumTimeBeforePersistenceConsidered and MaximumTimeBeforePersistenceConsidered.
Example command or setting: verify before use.
[Startup] UpdateStorageEveryNFrames = 200
Object persistence
The reference values 60 and 600 seconds prevent every object change from being written immediately. Lowering them can increase storage pressure; raising them delays when updates become persistent. Consider durability.
Example command or setting: verify before use.
[Startup] MinimumTimeBeforePersistenceConsidered = 60 MaximumTimeBeforePersistenceConsidered = 600
Physics, collision meshes and objects
Choosing the physics engine
The inspected fork sets physics = ubODE and meshing = ubODEMeshmerizer in OpenSimDefaults.ini. Do not assume older BulletSim examples are universal recommendations: compare stability, vehicles, collisions, startup and memory on a test region.
Example command or setting: verify before use.
[Startup] physics = ubODE meshing = ubODEMeshmerizer
Complex meshes
Detailed collision shapes can increase CPU and loading time. For static decoration, simplify collision meshes or select a non-colliding physics setting where the object need not obstruct avatars.
Phantom, physical and solid
Phantom objects do not act as ordinary obstacles; physical objects respond to forces and often need more computation. A nonphysical solid object does not have the same cost as a vehicle or movable object.
Find costly objects
Use viewer statistics and, where available, Top Colliders and Top Scripts in region/estate tools. Support varies by engine, version and permissions. Do not blindly disable all scripts.
Why changing engines may regress
A physics engine that starts faster may consume more RAM or behave differently with collisions. Startup speed alone is insufficient. Check mesh decode errors and vehicle behavior.
Scripts, YEngine and optimization
YEngine on modern releases
The inspected configuration describes YEngine as the scripting engine. Do not extrapolate old XEngine behaviors to modern .NET 8 builds without verification.
Timers and sensors
Hundreds of frequent timers or recurring sensors can be expensive. Use the longest acceptable interval and prefer events where possible.
Avoid constant object updates
A script constantly changing position, texture or text can stress scripts, simulation and network. If the value has not changed, do not emit the same operation again.
Find most expensive scripts
Use Top Scripts where supported and compare before/after changes. High load may come from many modest scripts rather than a single slow script.
Control OSSL permissions
Never disable OSSL security restrictions just to speed up troubleshooting. They protect regions from sensitive functions; exceptions should be narrow and justified.
Assets, caches, MySQL, ROBUST and network
Identify the slow service
A texture loading late may be due to the viewer, network, cache, asset service or storage. Slow teleports may involve inventory or presence services. Distinguish loading delays from simulation lag.
MySQL: connectivity and response time
Review MySQL and OpenSimulator logs, dropped connections, slow queries and disk waits. Blindly raising connection limits may hide leaks or increase RAM pressure.
Caches: trade-offs
Caches trade memory or disk use for faster repeated access. Clearing all caches indiscriminately can increase load and degrade experience temporarily. Measure before and after.
Networking and DNS
Check internal/external DNS, ports, timeouts, firewall and service logs. Networking failures may look like simulator performance problems.
Separate ROBUST from regions
In distributed grids, examine ROBUST and simulators separately. Slow ROBUST services can affect many regions even when simulator hosts are not saturated.
Viewer-side performance and 3D content
Viewer FPS versus Sim FPS
A slow viewer does not necessarily mean an overloaded server. Check GPU, resolution, field of view, draw distance and rendered object count before touching simulator settings.
Textures and VRAM
Use the lowest texture resolution that still looks good at normal viewing distance. Reusing appropriate textures can reduce downloads and GPU memory. Avoid assigning 1024×1024 textures to every small object.
LOD and triangles
Meshes use multiple levels of detail. Good LOD reduces distant rendering cost. Distinguish display geometry from collision geometry.
Transparency and overdraw
Many overlapping transparent surfaces can burden the viewer and produce artifacts. Reduce transparency layers when practical.
Practical diagnostic cases
High CPU, available RAM
Start with top -H on the affected process, then inspect frame times, scripts and physics. Restarting may temporarily hide an issue without fixing it. Reproduce on a test region.
Example command or setting: verify before use.
top -H -p PID stats show
High RAM, low CPU
Check available and swap first. Compare process RSS over hours. If memory rises continuously under stable load, examine specific modules, caches or objects.
Example command or setting: verify before use.
free -h vmstat 1 10
High disk wait
If wa rises during backups or MySQL queries, inspect concurrent operations and storage latency. Scheduling backups apart may help more than physics changes.
Example command or setting: verify before use.
vmstat 1 10
Stuttering avatar, good viewer FPS
Check packet loss, ping, region stats and physics. Smooth viewer rendering does not guarantee timely position updates.
Viewer at 10 FPS, server healthy
Start with draw distance, LOD, mesh and texture complexity, GPU memory and drivers. Do not change FrameTime to fix local graphics saturation.
Slow teleports with idle regions
Correlate source, destination and ROBUST logs; check DNS, inventory, assets, presence and external services. A service issue can affect the entire grid.
Sources, releases and references
FrameTime, physics and statistics settings are checked against the fork. Mesh and scripting guidance is also cross-checked against community documentation. The official wiki may not always be accessible.