Guides Build & Release Understand Player-Mode Security and Permissions

Build & Release 3 min read Updated Apr 2026

Understand Player-Mode Security and Permissions

Use this guide when you want to understand what changes between a normal development run and a packaged player build.

The short version is:

  • development runs are more permissive
  • exported builds run in player mode
  • player mode uses a stricter default-deny PHP sandbox

Development Mode vs Player Mode

During normal development, Lenga prioritizes iteration speed and debugging.

During export, Lenga switches to a player-facing trust model:

  • packaged game content is treated as read-only
  • only the packaged Saved/ area is writable inside the export
  • Preferences writes stay in the engine-managed per-user preferences location
  • blocked PHP APIs stay blocked in the shipped player

This split is intentional. A player build should not have the same broad host access as a local development workflow.

The Player-Mode Permission Surface

Lenga records the shipped sandbox contract in build-manifest.json.

The permission surface is:

  • packaged game reads from the exported Game/ root
  • writes only to Game/Saved/
  • Preferences writes through the engine-managed preferences path
  • outbound networking denied by default
  • process execution denied
  • shell execution denied
  • dynamic extension loading denied
  • remote and special stream wrappers denied
  • stream-wrapper registration denied

This is the packaged player security baseline.

What Export Checks

Before export completes, Lenga scans project PHP files for common violations, such as:

  • process execution and unsafe host access
  • outbound networking
  • native code loading through FFI
  • remote or special stream wrappers like http:// or phar://

By default, export stops when those references are found.

If you intentionally turn on Restricted PHP APIs -> Allow packaging anyway, Lenga still records that override in build-manifest.json so the build can be reviewed honestly later.

What Runtime Failures Look Like

If a packaged build still reaches a blocked path at runtime, the failure shows up through:

  • normal console/runtime output
  • the packaged PHP log at Game/Saved/Logs/php-runtime.log

That means you should debug runtime sandbox failures the same way you debug other packaged script/runtime errors: check the console first, then inspect the saved PHP log for the full message and stack context.

Preferences Are Special

Preferences is allowed in shipped builds, but it does not widen general PHP write access.

That matters because:

  • Preferences is for small local settings
  • it uses the engine-managed per-user preferences store
  • it is separate from arbitrary file writes in PHP

So a build can safely use Preferences without implying “PHP can write anywhere.”

What Player Mode Does Not Include

Player mode does not include:

  • a user-facing permission prompt system
  • mod/plugin permission approvals
  • a large capability matrix per script

The goal is a clear, conservative shipped baseline, not a complicated desktop permission UX.

Related Guides