š 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.
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.
Open-source repository
CI-Virtual-Home is open source under the PolyForm Noncommercial 1.0.0 license:
- Source code:
github.com/companionintelligence/CI-Virtual-Home - Live experience:
homes.ci.computer(deployed to Cloudflare Pages frommain) - Specification standard:
reference/HOUSE-SPEC.md
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.
| Address | homes.ci.computerĀ |
| Runs in | Web browser via Three.js (desktop, mobile, Quest 3, Apple Vision Pro) |
| Catalog | 36 homes (30 houses + 6 urban apartments) |
| Hosting | Cloudflare 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.
flowchart TD
SPEC["HouseSpec v1 JSON<br/>content/houses/<id>.json"]
subgraph COMPILERS["Multi-Target Compilation Matrix"]
B3D["Three.js 3D Builder<br/>assets/house-builder.ts"]
SPLINE["Spline Planner v2<br/>assets/splines.ts"]
CAD["Python CAD Generator<br/>scripts/generate_floor_plans.py"]
ISO["Isometric & Lottie Engine<br/>scripts/generate_house_iso.py"]
VIDEO["Headless Chromium Renderer<br/>scripts/render-house-shots.mts"]
end
subgraph OUTPUTS["Artifacts & Surfaces"]
WEB["Interactive 3D Web Viewer<br/>room-creator.html?house=<id>"]
BLUEPRINT["Architectural Blueprints<br/>scenes/floorplans/ (SVG + PNG)"]
LOTTIE["Vector Lottie Animations<br/>scenes/lottie-scenes/ (*.json)"]
MP4["Deterministic 4K Video<br/>video/houses/*-door-to-core.mp4"]
PORTAL["Gallery Web Portal<br/>dist/ ā homes.ci.computer"]
STORY["Family Persona Narratives<br/>family/<slug> uncloud stories"]
end
SPEC --> B3D & SPLINE & CAD & ISO & VIDEO
B3D & SPLINE --> WEB
CAD --> BLUEPRINT
ISO --> LOTTIE
VIDEO --> MP4
SPEC --> STORY
WEB & BLUEPRINT & LOTTIE & STORY --> PORTALThe 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
+Yup. The origin(0, 0)represents the geometric center of the building lot. +Zpoints South toward the street and front entry of the home;-Zpoints North toward the backyard.+Xpoints 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,wspans+X(width), anddspans+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:
- Wall meshing and openings: Wall segments are extruded into 3D geometry with window and door openings calculated using boolean geometric subtractions.
- Material shader bindings: Surfaces receive physically based rendering (PBR) materials with roughness and normal mapping matching the palette specification.
- 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 path | Trajectory & purpose | Framing target |
|---|---|---|
| Door to Core | Enters 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 reveal | High-angle crane shot descending toward the room containing the Core. | Low-angle dynamic push-in emphasizing sovereign hardware. |
| Walkthrough | Interior tour traversing ground-floor living areas, up staircases, and through bedrooms. | Eye-level human walking perspective (1.65 m elevation). |
| Orbit | 360-degree exterior orbit at a 30-degree pitch angle. | Lot centroid framing full architectural massing. |
| Core orbit | Close-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 fractionst ā [0, 1], saving raw PNG frames and encoding 4K H.264 video withffmpeg.
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| Parameter | Options | Description |
|---|---|---|
house | Any house ID (e.g. aurora, bellevue, solstice) | Selects which content/houses/<id>.json spec to compile. |
shot | door-to-core, hero-reveal, walkthrough, orbit, core-orbit | Active procedural camera spline. |
t | Number from 0.0 to 1.0 | Scrub to an exact normalized moment in the camera path. |
lighting | day, golden, dusk, night | Solar angle and ambient lighting configuration. |
mode | view (portal viewer) or edit / review (inspector HUD) | Switches between consumer showcase and developer debugging view. |
flythrough | 1 or 0 | Automatically 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)
ffmpegandrsvg-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 goldensGet 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.