Getting Started

Thanks for your interest in contributing to the project! This guide will help you get started with the development environment and the project structure.

Prerequisites

In order to contribute to this project, you need to have Godot 4.2.x installed on your computer.

Git and Git-LFS is also required to clone the repository and download the large binary files.

Local Development

1. Clone the repository from GitHub:

git clone https://github.com/Nitwel/Immersive-Home.git

2. Open the project in your Editor of choice. We recommend using Visual Studio Code with the Godot Tools extension.

3. Open Godot and import the project by selecting the project.godot file in the root of the repository.

WARNING

Development is currently only supported on Windows and Linux. If you are using a Mac, the project might not work correctly due to the godot-cdt addon only having binaries for Windows and Linux.

Fundamentals

Communication with the Smart Home Environment is done using the HomeApi global. Each environment is made up of devices and entities. A device is a collection of different entities and entities can represent many different things in a smart home. For example, the entity of name lights.smart_lamp_1 would control the kitchen lamps while state.smart_lamp_1_temp would show the current temperature of the lamp.

File Structure

.
├── app/               (Main Godot Project)
│   ├── addons             (All installed Godot Addons are saved here)
│   ├── assets             (Files like logos or assets that are shared across scenes)
│   ├── content/           (Main files of the project)
│   │   ├── entities       (Entities that can be placed into the room)
│   │   ├── functions      (Generic functions that can be used in scenes)
│   │   └── ui             (User Interface Scenes and related files)
│   └── lib/               (Shared code)
│       ├── globals        (Globally running scripts)
|       ├── home_apis       (Code that communicates with the smart home environment)
|       ├── stores         (Stores that hold the state of the app)
│       └── utils          (Utility functions)
├── docs/              (Documentation)
│   ├── development        (Development related documentation)
│   ├── getting-started    (Getting started guides)
│   └── vendor-integration (Integration guides for different smart home vendors)
└── vendors/          (Vendor specific code)
    └── home-assistant_integration (Home Assistant Integration)

Scene Structure

When the app starts, globals and the main.tscn are loaded. The main.tscn is the main scene of the app and is responsible for loading the other scenes.

root
├── HomeApi      (Global access for talking to the smart home environment)
├── EventSystem  (Global Event System)
├── Store        (Global access the the app state)
├── House        (Global House reference to the current house)
└── Main         (Main Scene)

Code Reference and Documentation

Static code reference can be found in the Reference section of the documentation at the top right. It is exported from Godot and contains all available scripts from the /lib folder.

The documentation is written in Markdown and can be found in the docs folder of the repository.

Physics layers

1. Entitites: Used for interaction with entities in the room.
2. Interface: Used for interaction with the UI.
3. Touch: Used for touch based interactions.
4. Physics: Used for physics interactions.
5. Room: Used for interaction with the room.