Environment and Configuration

Runtime helpers for reading environment variables and managing persistent key-value storage.

`aura.env(name)`

Read an environment variable at runtime.

const apiKey = aura.env("GEMINI_API_KEY");
const debug = aura.env("DEBUG");

Signature: aura.env(name: string) -> string | null

• Returns the value of the environment variable as a string, or null if unset/empty.
• name must be a non-empty string.
• Environment variables are read from the host process environment and from .env files in the project root.
• This is a local-machine/runtime convenience for project-owned runs such as auramaxx dev, auramaxx run, and npm run play inside the project root.
• Published game launches through auramaxx play <game> preserve the local shell environment, so exported vars remain available there too.
• .env files are still a project-root convenience. For published wrapper runs, export the vars you want in the local shell before launching.
• auramaxx publish does not ship the real project .env; when .env exists it generates a blank .env.example from the declared keys and publishes that instead.

Use cases:

• API keys for external services (AI, analytics, leaderboards)
• Debug/development flags (DEBUG=1, LOG_LEVEL=verbose)
• Server URLs or feature toggles that vary per environment

Best practices:

• Store secrets in a .env file and add it to .gitignore — never commit API keys.
• Use .env for local machine secrets/config, and export those vars in the shell when you want the published wrapper lane to see them too.
• Treat the generated .env.example as documentation of required keys, not as a secret-bearing file.
• Check for null before using the value:

const key = aura.env("MY_API_KEY");
if (!key) {
  console.log("MY_API_KEY not set — feature disabled");
}

`aura.storage`

Simple persistent key-value store for save data, preferences, and local state. Data persists across sessions.

• save(key, value) — write a value (string, number, boolean, or JSON-serializable object)
• load(key, fallback?) — read a value, returning fallback (default undefined) if not found
• delete(key) — remove a key
• keys() — list all stored keys

Legacy aliases: set(key, value), get(key, fallback?)

// Save player preferences
aura.storage.save("volume", 0.8);
aura.storage.save("username", "Alex");

// Load with fallback
const vol = aura.storage.load("volume", 1.0);
const name = aura.storage.load("username", "Player");

// List and clear
const allKeys = aura.storage.keys();
aura.storage.delete("username");

Use cases:

• Player preferences (volume, controls, accessibility)
• Save game metadata (level, score, unlocks)
• Local high scores and achievement flags

When to use `aura.env` vs `aura.storage`