Skip to content
Go to file

Latest commit


Git stats


Failed to load latest commit information.

πŸ—οΈ aframe-city-builder

A-Frame project demonstrating touch controls for building a VR city scene.

Build a New City Now: >> <<

HTC Vive or Oculus Rift with accompanying controllers required to add items to scene.

Load Existing City


* * * *

Feature Highlights

  • Place voxel objects in a fun virtual city of your creation
  • Navigate available voxel objects with a scrolling menu interface in VR
  • Place base plates for streets, grass, parks and residential lots that snap to a simple grid layout
  • Save and load your city to/from JSON format
  • Support for Oculus Touch and HTC Vive Controllers (VR headset and controllers required)
  • Convenience utilities in /utils for creating new object JSON groups for aspiring city voxel artists


How do I add new objects to City Builder?

City Builder is only as cool as the objects you can place! So let's add more! (Some day I'd love to have a sketchfab-like fancy cloud interface for uploading objects, an in-app voxel editor and more, but for now you'll have to do a bunch of manual work.)

Step-By-Step Guide

(1) Make the object - I suggest using MagicaVoxel:

(2) Come up with a filename - Each object has unique filename according to this suggested naming convention: "creator_group_object". For example "kfarr_bases_valencia" or "mmmm_obj_candle".

(3) Export to OBJ and take preview image For each object, there are multiple files using the same filename but with different extensions to represent their function in the application:

  • .jpg - A preview image used to represent the object in a menu interface, stored here: /assets/preview/. Should be 1:1 aspect ratio, suggested 256 x 256 dimensions. (Required)
  • .obj, .mtl, .png - Object file format used when placing into A-Frame scene, stored as three files per model here: /assets/obj/ (Required)
  • .vox - The object's raw source file that can be edited again in the future, stored here: /assets/vox/ (Optional)

(4) Add to JSON File - To enable placement of the object within the City Builder app, the object needs to be included in a "creator_group" JSON file. Here's an example: /assets/mmmm_veh.json

To make it easier to add a large number of objects at once, there is a utility script to create a new "creator_group" JSON file here: /utils/json_builder.js

(5) Load JSON file from City Builder - You must add the newly created JSON "creator_group" file to the list of included model definitions upon load of City Builder app. Add your filename to this list:

(5) Test it out! Take a screenshot while you're testing! Submit a pull request and include a note and your fancy screenshot!

Need inspiration? What are some other objects to make?

  • more cool vehicles
  • flying things
  • more "bases" like intersection, left turn, right turn, green park only, pedestrian and bike path only
  • more advanced light poles, signals, signs
  • people
  • trains

How can I contribute to City Builder?

Fork this repo, start making changes, and submit a pull request! Also feel free to file an issue or reach out directly with your idea and I can try to help make your idea work.

Need inspiration? Here is a partial wishlist for City Builder features:





πŸ—οΈ A-Frame project demonstrating touch controls for building a VR city scene




No packages published

Contributors 4

You can’t perform that action at this time.