Skip to Content
DocumentationVirtual Homes

šŸ  Virtual Homes

Walk into thirty-six homes. Your browser builds each home live from a single declarative specification file: walls, rooms, openings, stairs, furniture, garden, and lighting. Pick a home, fly procedural camera paths, and inspect the Companion Core on every desk.

Open the live site homes.ci.computer

Virtual Homes is a Web3D experience running in your browser. The compact computer on every desk is a Companion Core running your local AI, apps, and memory.

Get a Companion Core, a personal AI appliance and local server, or download Companion Hub to turn a computer you already own into one.Buy Companion Core →Download Companion →Back to ci.computer
The Companion Core in Virtual Homes: hardware-anchored personal AI and sovereign memory woven into architectural space.

Open-source repository

CI-Virtual-Home is open source under the PolyForm Noncommercial 1.0.0 license:

Availability and overview

Available now on the web. Open homes.ci.computerĀ  in any modern browser with WebGL2 support. No plugins, downloads, or accounts required.

Addresshomes.ci.computerĀ 
Runs inWeb browser via Three.js (desktop, mobile, Quest 3, Apple Vision Pro)
Catalog36 homes (30 houses + 6 urban apartments)
HostingCloudflare Pages static edge network

Every home in the catalog is the residence of a fictional family whose personal stories demonstrate the case for unclouding: running AI assistants, private family photo archives, and local device automation on a self-hosted Companion Core rather than renting compute from remote cloud platforms.

What’s on the site

  • A gallery of 36 homes. Each card shows the home’s name, a one-line description, its number of storeys, its floor area in square metres, and the builder it is credited to. (The repository catalog includes 30 houses and 6 urban apartments.)
  • Filters. Narrow the gallery by number of storeys (1, 2, or 3+) and by tags such as Modern, Cottage, Mediterranean, Pool, Garden, Waterfront, Porch, Brick, Stone, and Timber. Each tag shows how many homes carry it.
  • A featured home. Watch Aurora opens Aurora, a layered white modern villa on a canal.
  • Play in 3D. Every card opens that home in a 3D player.

In a home

  • Camera paths. Five paths are on offer: Door to Core, Orbit, Core orbit, Hero reveal, and Walkthrough. Each lists its length.
  • Time of day. Switch between Day, Golden hour, Dusk, and Night.
  • Move between homes. Previous home, Next home, and All homes take you through the gallery from inside the player.
  • Share and fill the screen. The player has a Copy a link to this moment button and a Full screen button.

Architecture and subsystems

Virtual Homes is designed around a single architectural principle: one declarative specification file is the single source of truth, and every visual, technical, and architectural artifact is compiled deterministically from it.

The HouseSpec v1 data contract

Each home is defined by an individual JSON document adhering to the HouseSpec TypeScript schema (assets/spec/index.ts):

  • Coordinate system:

    • Metric units (metres).
    • Vertical axis is +Y up. The origin (0, 0) represents the geometric center of the building lot.
    • +Z points South toward the street and front entry of the home; -Z points North toward the backyard.
    • +X points East. The default isometric camera looks from the south-east, creating a natural cutaway effect on South and East exterior walls.
    • Rectangular volumes are defined by { x, z, w, d } where (x, z) is the north-west minimum corner, w spans +X (width), and d spans +Z (depth).
    • Rotations are measured in degrees counter-clockwise when viewed from above (0° faces South).
  • Core spec sections:

    • lot: Overall dimensions (w, d) and environmental terrain type (lawn, desert, forest, urban, waterfront).
    • palette: Material tokens (stucco, siding, brick, stone, timber, corrugated, glass) and hex color definitions for walls, trims, roofs, and interior accents.
    • levels: Array of floor storeys containing room boundaries, exterior wall polygons, partition walls, door/window openings, floor finishes, and ceiling slab voids (stair openings).
    • roofs: Parametric roof geometries including flat slabs, hipped roofs, gabled peaks, and shed pitches.
    • site: Exterior landscaping fixtures including swimming pools, patio paving, perimeter fences, outdoor lighting, and procedural trees.
    • hero: Spatial coordinate, level, rotation, and desk fixture defining the placement of the Companion Core appliance.

Procedural 3D scene assembly (Three.js r169)

The browser runtime (assets/house-builder.ts) compiles the JSON spec into a Three.js scene graph in real time without external bundler overhead:

  1. Wall meshing and openings: Wall segments are extruded into 3D geometry with window and door openings calculated using boolean geometric subtractions.
  2. Material shader bindings: Surfaces receive physically based rendering (PBR) materials with roughness and normal mapping matching the palette specification.
  3. Solar lighting simulation: Four lighting configurations alter sun vector coordinates, ambient sky irradiance, and shadow map cascades:
    • Day: High-noon direct solar lighting (5,500 K) with sharp directional shadows.
    • Golden hour: Low-angle warm sunlight (3,200 K) with long indoor light penetration.
    • Dusk: Deep blue ambient sky dome with warm interior lamp illumination.
    • Night: Dark exterior environment highlighting interior accent LEDs and the glowing Companion Core status indicator.

Procedural camera spline planner (planner=v2)

The spline engine (assets/splines.ts) synthesizes camera paths through the house without manual keyframing:

Camera pathTrajectory & purposeFraming target
Door to CoreEnters the front gate, passes through the threshold, moves down the main hallway, and glides into the study.Finishes in a tight orbit framing the Companion Core on the desk.
Hero revealHigh-angle crane shot descending toward the room containing the Core.Low-angle dynamic push-in emphasizing sovereign hardware.
WalkthroughInterior tour traversing ground-floor living areas, up staircases, and through bedrooms.Eye-level human walking perspective (1.65 m elevation).
Orbit360-degree exterior orbit at a 30-degree pitch angle.Lot centroid framing full architectural massing.
Core orbitClose-up rotational inspection of the Companion Core appliance.Hardware ports, cooling fin details, and status LED.

Deterministic video and Lottie pipelines

  • CAD floor plans (scripts/generate_floor_plans.py): Generates dimensioned 2D blueprints with room labels, door swing arcs, and furniture outlines, saving both vector SVGs and high-resolution PNGs.
  • Isometric vector cutaways (scripts/generate_house_iso.py): Calculates south-east isometric projections with removed cutaway walls, generating interactive Lottie animations (scenes/lottie-scenes/house-<id>.json) for web embedding.
  • Frame-stepped headless video (scripts/render-house-shots.mts): Uses Playwright to drive headless Chromium with GPU hardware acceleration. The script advances the camera along splines using deterministic time fractions t ∈ [0, 1], saving raw PNG frames and encoding 4K H.264 video with ffmpeg.

URL parameters and developer controls

When loading room-creator.html, URL parameters configure the runtime scene:

# View Aurora house during golden hour flying the Door to Core path https://homes.ci.computer/room-creator.html?house=aurora&shot=door-to-core&lighting=golden&planner=v2
ParameterOptionsDescription
houseAny house ID (e.g. aurora, bellevue, solstice)Selects which content/houses/<id>.json spec to compile.
shotdoor-to-core, hero-reveal, walkthrough, orbit, core-orbitActive procedural camera spline.
tNumber from 0.0 to 1.0Scrub to an exact normalized moment in the camera path.
lightingday, golden, dusk, nightSolar angle and ambient lighting configuration.
modeview (portal viewer) or edit / review (inspector HUD)Switches between consumer showcase and developer debugging view.
flythrough1 or 0Automatically plays the selected camera spline on load.

Quickstart and local development

Prerequisites

  • Node.js ≄ 22.15
  • pnpm 10 (corepack enable)
  • Python 3 with pip
  • Git LFS (required for golden image test fixtures)
  • ffmpeg and rsvg-convert (for video rendering and floor plan rasterization)
# 1. Clone repository and install dependencies git clone https://github.com/companionintelligence/CI-Virtual-Home.git cd CI-Virtual-Home git lfs install pnpm install # 2. Build TypeScript assets pnpm run build # 3. Start local development server pnpm run serve # Editor: http://localhost:8080/room-creator.html?house=aurora # Portal: http://localhost:8080/

Verification commands

pnpm run validate # Validates all content/houses/*.json specs against the TypeScript schema pnpm run floorplans # Recompiles all CAD blueprint sheets pnpm run iso # Generates isometric SVGs and Lottie scene files pnpm run check # Executes Playwright visual diff regression tests against committed goldens

Get a Companion Core

To put a real Companion Core on your own desk, buy one at ci.computer/coreĀ  and follow Set up a Companion Core when it arrives. To start on a computer you already own, download Companion Hub from ci.computer/downloadĀ  and begin with Your first hour.

Last updated on