Skip to main content

Adamas VR Coding Guidelines

This document provides general programming guidelines for developing Adamas VR projects. It focuses on runtime code structure, async safety, networking, and performance.

info

This document is intended for experienced developers, and it will continue to be updated as development practices evolve. New users with limited programming experience may skip this document and begin with the broader project setup and Project Studio documentation instead.

Runtime Code Structure​

  • Treat OnSetup as the main startup path for runtime initialization to read the scene graph, cache entity IDs, fetch meshes or materials, prepare reusable runtime objects, and register callbacks.
  • Keep OnSetup focused on startup wiring. Long-running simulation, benchmarking, or data-processing tasks should usually begin only after setup has completed.
  • Treat ScheduleUpdate as a hot per-frame path. Keep it small and avoid expensive awaited work whenever possible.
  • Do not call Adamas runtime APIs at module load time. Create entities, channels, network variables, network functions, and other SDK runtime objects in OnSetup or later.

Async and State Safety​

Adamas API calls are asynchronous and may cross multiple runtime frames. Code should not assume that shared state remains unchanged across an await.

  • Capture the target object in a local variable before await, and use that captured reference after the await resumes.
  • Keep procedurally created entities or components inactive until asynchronous setup has completed, so users do not observe partial cross-frame state.
  • When several getter calls are required for one calculation, start them together with Promise.all before performing the dependent logic.

Networking Guidelines​

  • For high-frequency updates, separate local sampling from network transmission. Queue local data continuously and send it on a fixed ScheduleUpdate step instead of using wall-clock timers.
  • When synchronizing streamed data followed by a terminal event, preserve ordering by flushing queued data before sending the final event.

Performance Guidelines​

  • Avoid creating entities, renderables, meshes, or materials inside hot interaction paths when possible. Pre-create or pool them instead.
  • When a renderable mesh may become visible before later runtime setup completes, assign a usable material immediately so the engine does not show a transient missing-material shader.
  • Avoid overlapping expensive updates. If an update is already in progress, queue a single follow-up refresh instead of starting multiple concurrent refreshes.
  • Rebuilding full geometry or large buffers every frame can become expensive. Prefer batching, throttling, pooling, or incremental update strategies when appropriate.