Environments
The Environments app swaps the world around the player for a 360° panorama. The windows stay where they are; only what is behind them changes.Why they are not included
One 8192×4096 equirectangular JPG is around 36 MB, and every player downloads it once, in full. Shipping two or three would add a hundred megabytes to a resource for pictures that may not suit your server at all. Which panoramas belong on your server is your decision, not ours.What a panorama file looks like
Where to get them
Poly Haven
Free, CC0, no attribution required. The two examples commented into
config.lua come from here.Config.Environments.list ships empty, with those two written above it as
a comment to copy:
config.lua
Adding one
1
Convert it
Download the tonemapped JPG, then re-encode to WebP at 4096×2048,
quality 90:This matters more than anything else on this page. The two examples went
from 72 MB to 3.8 MB with no visible difference on the sphere — and that is
72 MB every single player would have downloaded.
texture below scales anything larger down to 4096 anyway, so the extra
pixels only ever cost the download and the decode.2
Drop it in
Put the file in
public/environments/.WebP, JPG and PNG all work. WebP first, because at equal quality it is by
far the smallest of the three.3
Register it
config.lua
id has to stay stable — it is what a player’s saved choice points at.
label is what they see in the picker and can be changed any time.4
Restart
The rest of the block
number
default:"0.85"
Where the slider starts when a panorama is picked.
1.0 is fully opaque.number
default:"1.4"
Metres per second. Walk faster than this and the panorama pulls back so the
player can see where they are going.
number
default:"700"
Milliseconds of standing still before it comes back.
table
default:"{ 'basketball', 'drone', 'gps' }"
Apps that may not be open while a panorama is up, by app id.All three put something into the world rather than into a window — the
hoop, the drone, the map table’s surroundings — and the sphere is exactly
what stands between the player and the world. An app that is only a window
has no reason to be listed: it sits inside the sphere and stays perfectly
readable.It works both ways: opening one while an environment runs is refused with a
notification, and starting an environment closes the ones already open.
Leave the list empty to switch the rule off entirely.
number
default:"4096"
Maximum edge length in pixels, capping video memory only. A 4096 panorama
costs about 45 MB including mipmaps, an 8192 about 180 MB — and the GPS map
table wants its share of that budget too.
Troubleshooting
The tile is there but the sphere stays empty
The tile is there but the sphere stays empty
The file name in
config.lua does not match the file in
public/environments/. Check the extension too — .webp and .jpg are
two different files.It stutters for a second when it opens
It stutters for a second when it opens
The file is too large. Re-encode to 4096×2048 WebP. Lowering
texture will
not help — see the warning above.The image is stretched or the horizon bends
The image is stretched or the horizon bends
It is not equirectangular. The source has to be a 2:1 360° image; a normal
photo or a 16:9 render cannot cover the sphere.
An app refuses to open while an environment is running
An app refuses to open while an environment is running
That is
blockedApps doing its job. Remove the app id from the list if you
would rather allow it.