ARsemble

An educational AR robotics app for iPad. Students build a virtual robotics playground in Augmented Reality and experiment with how robot components affect movement and behavior.

Built with SwiftUI, RealityKit, and ARKit.

Tech Stack

• SwiftUI — UI layer
• RealityKit — rendering and physics (prefer built-in physics over manual movement calculations)
• ARKit — world tracking and horizontal plane detection
• XcodeGen — project generation (.xcodeproj is generated, not committed)

Getting Started

This project uses XcodeGen. The .xcodeproj and Info.plist are not committed — they are generated locally.

# Install XcodeGen (once)
brew install xcodegen

# Generate the Xcode project
xcodegen generate

# Open it
open [ProjectName].xcodeproj

Project Structure

Features
├── Commons
│   ├── 3DModels
│   │   ├── ModelA.usdz
│   │   └── ModelB.usdz
│   ├── Components
│   └── Extensions
└── Feat1
    ├── View
    ├── ViewModel
    ├── Models
    └── Components

• Keep AR logic separate from UI logic.
• Prefer reusable systems over hardcoded implementations.
• Shared code (models, components, extensions) lives under Commons.
• Each feature is self-contained with its own View, ViewModel, Models, and Components.

Naming Conventions

1. Folders use Capital case (e.g. Features, View, ViewModel).
2. File names end with their type. A view model for Home is HomeViewModel, a view is HomeView, a model is HomeModel.
3. Reusable code goes in a Components folder — either Commons/Components (app-wide) or Feat/Components (feature-scoped).
4. .xcodeproj and Info.plist are not pushed — they're generated by XcodeGen and listed in .gitignore.

Branching Convention

Branch names follow feat/featname.

feat/plane-detection
feat/robot-movement

Commit Message Convention

Prefix each commit with its type:

Type	When to use
init	The first thing you init the project
feat	Adding a new feature that doesn't exist yet
mod	Modifying an existing feature
docs	Adding documentation (README, etc.)
fix	Fixing a bug or error

Add an optional (scope) after the type for more detail and categorization:

init: setup project with xcodegen
feat: add horizontal plane detection
feat(api): add API gateway services
mod: adjust robot spawn logic
docs: add README
fix: resolve entity collision crash

Coding Style

• Follow the Swift API Design Guidelines.
• Use clear, descriptive naming.
• Keep code modular, reusable, and maintainable.
• Avoid unnecessary complexity.
• Comment only when necessary.
• Always prefer RealityKit's built-in physics system over manually calculating movement.