Game Module Architecture & API Documentation

We've repeatedly encountered teams spending weeks debugging cross-module interactions. For example, in one VR Unity project with 15 modules using Zenject, a bug in the SaveSystem module only appeared on the device because the editor used PlayerPrefs, but the production build used a cloud API. The developer spent 3 weeks finding the root cause: there was no documentation describing this difference.

Documenting game module documentation and game architecture documentation solves this. After implementing documentation, onboarding new developers dropped from 2 weeks to 2 days — an 86% reduction. Team budget savings from reduced maintenance time reached 40%.

Valuable game architecture documentation answers three key questions: why this was done this way, what happens in edge cases, and what does it interact with. Without these answers, code remains a black box.

What Makes Game Module Documentation Truly Useful

The biggest mistake is documenting what the method does when it's obvious from the signature. /// <summary>Adds item to inventory</summary> above AddItem(Item item) is a useless line. Instead, capture non-obvious details: why the module uses Service Locator instead of DI, how it behaves on re-initialization, what resources it frees in OnDestroy. Comparison: documented modules debug 3x faster than undocumented ones.

For game projects, documentation on states and dependencies is especially critical. A SaveSystem that works via PlayerPrefs in Editor and via cloud API in production is non-obvious behavior that must be explicitly described. Otherwise, a developer writes a test that passes locally and fails on the device.

The second layer is documentation on data flows between modules. In Unity projects with Zenject or VContainer, dependencies are injected, and the IDE doesn't always hint where a particular service came from. A one-page Architectural Decision Record (Wikipedia) with a dependency diagram saves hours during onboarding.

Why Documentation Structure Matters

For modular game architecture, we build documentation on several levels:

• Architecture overview — module diagram and their dependencies (PlantUML or Mermaid, embedded in Markdown in Confluence/Notion). Must include: layers (Presentation, Domain, Infrastructure), dependency directions, what is Singleton, what is created via factory.
• Module cards — for each major module: purpose, public API, events it emits and subscribes to, initialization requirements (Awake/Start order), known limitations.
• API Reference — generated from XML comments via DocFX. For C# Unity projects, DocFX produces clean HTML with navigation. We configure auto-generation in CI: documentation updates on every push to main.
• Use-case scenarios — concrete code examples for non-obvious cases. Not public void Initialize() with parameter descriptions, but how to properly initialize WeaponSystem in a scene where there is no PlayerController at start time.
• XR Interaction Flow — for VR/AR projects: description of event sequence from SelectEntered to SelectExited in XR Interaction Toolkit, controller button mapping, specifics of working with different HMDs (Quest vs Pico vs HTC Vive).

Tools for Documentation

We write code comments using XML doc convention (C#): <summary>, <param>, <returns>, <exception>, <remarks> — the last one for non-obvious behavior details.

Work Process

1. Audit existing codebase. Read code, identify non-obvious patterns, module coupling points, non-standard solutions.
2. Interview developers. Ask about decisions not explained in code. Record as ADRs.
3. Create documentation structure. Decide where documentation lives (Confluence, GitHub Wiki, standalone DocFX site), which format for which task.
4. Write and mark up. Document modules by priority: first the most critical and opaque.
5. Set up auto-generation. CI pipeline to update API Reference on code changes.
6. Review with team. Developers confirm correctness, identify gaps.

What's Included

• Full codebase audit with identification of non-obvious decisions
• Module cards for each major module (up to 20 for an average project)
• API Reference with auto-generation via DocFX or Doxygen
• Dependency diagrams in Mermaid (embedded in Markdown)
• XR Interaction Flow for VR/AR projects
• CI pipeline setup for automatic updates
• Two-week post-delivery support: fixes based on team feedback

Pricing is determined individually after analyzing the codebase size and documentation format requirements. Our experience with over 20 game documentation projects and 5+ years of specialization in game architecture documentation confirms the effectiveness of our approach — maintenance time savings reach 40%.

Contact us to evaluate your project — we'll suggest the best format and timeline. Order an audit of your current documentation to identify which modules need descriptions first. Get a consultation on integrating documentation into your CI pipeline. We guarantee that after our work, no new developer will waste a day hunting for dependencies.

VR and AR Development

When we first launch a project in a VR headset, most teams face the same thing: technically everything works, but in the headset either motion sickness occurs, or hands 'float' with a delay, or the scene looks jerky at the periphery. These are not bugs in the usual sense — they are a consequence of the fact that VR/AR development requires a different approach to render architecture, interaction, and UX from the very beginning of the project. Our experience: over 7 years in game dev, 15+ completed VR/AR projects for Meta Quest, SteamVR, PSVR2, HoloLens. We work with teams that need not just a prototype but a production‑ready application with a stable frame rate.

Platforms and SDKs

We work with all relevant stacks. We use OpenXR as the base layer wherever possible — it provides cross‑platform compatibility between Meta, Valve Index, HP Reverb and other PC VR devices. On top of OpenXR, we build on the XR Interaction Toolkit (Unity) or VR Expansion Plugin (Unreal). Contact us for a stack assessment tailored to your project.

How to minimize motion sickness in VR locomotion?

Locomotion — the main source of motion sickness for inexperienced VR users. According to research, about 70% of users experience discomfort with improper movement settings Oculus Developer Guidelines. Teleportation — standard navigation method when smooth movement is undesirable.

Components from XR Interaction Toolkit: TeleportationArea, TeleportationAnchor, TeleportationProvider. Basic implementation works out of the box, but for production we refine it in four steps:

1. Setting up XRRayInteractor with a curved ray (Bend Ray) — the teleportation arc looks more natural than a straight ray and is perceived better by users.
2. Adding a valid landing zone — a visual indicator changes color when hovering over an obstacle (red/green).
3. Implementing fade transition — smooth screen fade (black fade) before teleportation reduces disorientation.
4. Rotation snapping — after teleportation we offer snap rotation by 45° or 90° instead of smooth, reducing motion sickness risk.

For projects requiring smooth locomotion (action games, simulators), we use comfort settings: vignetting during movement, reducing FOV during acceleration. Settings are available to the user in the menu — different people have different sensitivity thresholds. The difference between kinematic and physics‑based movement: kinematic gives instant hand following but lets objects pass through walls; physics‑based via Joint provides realistic collisions but requires velocity damping and max joint force tuning. We choose based on the type of interaction.

How to make object grabbing in VR physically realistic?

This is the most underestimated part of VR development. Clients often perceive it as 'just hand animation', but in practice it is a complex system where physical correctness, responsiveness, and comfort conflict.

Grab (grabbing)

XR Interaction Toolkit provides three types of Interactable for grabbing:

• XRGrabInteractable — standard grab, object follows controller via physics joint or direct position/rotation
• XRSimpleInteractable — for objects without physical movement (buttons, levers)
• Custom Interactable by inheriting from XRBaseInteractable

Attach Transform — a frequently ignored detail. Each Interactable must have a properly configured Attach Transform (the point where the hand 'attaches'). Without it, the pistol grip will be at the center of the mesh, not where it is held.

For weapons and tools with two‑handed grab — a separate TwoHandGrab system: leading hand determines position, the second — orientation. XR Interaction Toolkit supports this via XRTwoHandGrabInteractable or custom logic with two Attach Points.

Throw (throwing)

Velocity smoothing is critical for realistic throwing because the Rigidbody.velocity at the moment of controller release reflects instantaneous speed, often incorrect due to tracking discretization. The user makes a quick wrist movement — but the object flies half as fast.

Solution: velocity smoothing over the last N frames (typically 5–10 frames, ~80–160 ms at 60 Hz) before release. XR Interaction Toolkit does this via VelocityEstimator. Additionally, we apply a velocity scaling multiplier — a small speed increase (1.2–1.5×) makes throws subjectively more satisfying. Angular velocity (for objects that should spin in flight) is also averaged similarly.

AR: Plane Tracking and Environment Interaction

AR adds a different class of problems — working with real, unpredictable environment. AR Foundation — a cross‑platform layer on top of ARKit and ARCore. Most basic features (plane detection, raycasting, image tracking, face tracking) are available through a unified API.

Plane Detection

ARPlaneManager detects horizontal and vertical planes. Practical nuances:

• Initialization takes time — the user must look around the room while the system builds a map. An explicit onboarding with instruction 'slowly move the camera across surfaces' is needed.
• Planes are unstable — their boundaries and position are updated as data accumulates. Objects placed on a plane need to be attached via parent to ARPlane, not to world coordinates.
• Plane merging — two detected floor segments may merge into one, moving the anchor. For critical anchors, use ARAnchor instead of direct attachment to the plane.

Image tracking (via ARTrackedImageManager) quality directly depends on the quality of reference images. Images with high detail frequency and contrasting edges (like a QR code but stylish) track more reliably than smooth logos. ARCore Geospatial API — for outdoor AR with real‑world coordinate binding (accuracy up to 10 cm in well‑mapped areas).

Optimization for VR: Frame Rate and Comfort

VR requires stable high frame rate. About 60% of development time in mobile VR goes to optimization, not functionality — retrofit costs twice as much as proper architecture from the first sprint.

Single Pass Instanced Rendering

The main render optimization in VR. Without it, the scene is rendered twice (once per eye), doubling draw calls. Single Pass Instanced renders both eyes in one pass via instancing: geometry is processed once, the shader gets two view/projection matrices through GPU instancing. Enabled in Unity via XR Plug-in Management > Rendering Mode: Single Pass Instanced. Important: custom shaders must support SPI — standard URP/HDRP shaders support it, custom HLSL requires modifications (UNITY_SETUP_STEREO_EYE_INDEX_POST_VERTEX and related macros). Applying this technique reduces draw calls by 40–50%, making it twice as efficient as naive double rendering.

Foveated Rendering

On Meta Quest, Fixed Foveated Rendering (FFR) is available — reducing resolution at the periphery where visual acuity is lower. Configured via OVRManager or Meta XR SDK:

OVRManager.fixedFoveatedRenderingLevel = OVRManager.FixedFoveatedRenderingLevel.High;
OVRManager.useDynamicFixedFoveatedRendering = true;

Dynamic FFR automatically increases the level when frame rate drops — more convenient than fixed in scenes with variable load.

IPD and Comfort Settings

IPD (Inter‑Pupillary Distance) — affects depth perception. At the programmable level on most devices, only reading IPD is available (OVRPlugin.GetSystemDisplayFrequency), physical adjustment is on the headset. For applications requiring precise positioning (medical simulators, training), we account for IPD in scene scale calculations.

Haptics

Haptic feedback — an underestimated tool. Even a simple vibration response when grabbing an object or hitting significantly increases the sense of presence. On average, integrating haptic patterns takes 30–80 hours per project.

XR Haptics via OpenXR:

var hapticImpulse = new UnityEngine.XR.HapticCapabilities();
InputDevice device = InputDevices.GetDeviceAtXRNode(XRNode.RightHand);
device.SendHapticImpulse(0, amplitude: 0.5f, duration: 0.1f);

For complex patterns (tactile 'texture' of a surface when touched, increasing vibration when drawing a bowstring) we use Meta Haptics Studio — allows designing haptic clips visually. This can reduce time spent on manual haptic tuning by about 30%.

What does VR/AR application development include?

When ordering a turnkey project, we provide the following deliverables:

• Architectural document with stack description, render logic, and interaction system
• Working prototype (MVP) for testing on target device
• Integration of necessary SDKs (Meta XR, OpenXR, AR Foundation, etc.)
• Optimization for target frequencies 72/90/120 Hz with draw call and FPS profiling
• Testing on physical hardware (Quest, SteamVR, HoloLens) with user involvement
• Full documentation for build, deployment, and support
• Training for the client's team (workshop on XR Toolkit)
• Warranty support for 1 month after delivery

What affects cost and timeline?

VR/AR projects are more expensive than regular games of similar scope. Iterations are slower — each fix must be tested in the headset, an emulator does not convey the real experience. Motion sickness forces reworking some conceptual decisions after the first playtest. Optimization takes a significant portion of time — for mobile VR (Quest) up to 60–70% of the cycle. For Quest projects, we start optimization from the first sprint. The cost of basic SDK integration (XR Interaction Toolkit) varies depending on the scope of custom Interactable. Typical budgets for a full Quest project range from $25,000 to $80,000 depending on complexity, number of custom interactions, and depth of optimization. Proper architectural planning from sprint one typically saves 40% on later rework compared to fixing performance bottlenecks retroactively.

Get a consultation on your project — we will assess the task, stack, and timelines. Order turnkey VR/AR application development with a guaranteed stable frame rate.