> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ploterr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Start a building

> Make an empty building with one storey and show it in your scene.

export const LiveExample = ({path, title = 'Live example', height = 460}) => {
  return <Frame>
      <iframe src={`https://floorkit-examples.ploterr.com/floorkit/${path}?embed=1`} ref={frame => {
    if (!frame || !['localhost', '127.0.0.1'].includes(window.location.hostname)) return;
    const local = `http://localhost:5555/${path}?embed=1`;
    if (frame.src !== local) frame.src = local;
  }} title={title} loading="lazy" allow="fullscreen" style={{
    width: '100%',
    height: `${height}px`,
    border: 0,
    display: 'block'
  }} />
    </Frame>;
};

Each guide in this section adds one thing to a building. This guide makes the building that the other guides use.

<LiveExample path="guides/start-a-building" />

## Before you start

* You did the [installation](/floorkit/installation) and the geometry kernel is running.
* You have a Three.js scene.

## Make the building

<Steps>
  <Step title="Write an empty model">
    The model has one building with the id `building` and one storey with the id `ground`. The storey is 3 metres high.

    ```typescript theme={null}
    import * as THREE from 'three';
    import { BuildingSession, type BuildingModel } from '@opengeometry/floorkit';

    export const emptyBuilding: BuildingModel = {
      schema: 'floorkit.building-model',
      version: 3,
      units: 'meters',
      upAxis: 'y',
      id: 'my-building',
      buildings: [
        {
          id: 'building',
          storeys: [{ id: 'ground', name: 'Ground floor', elevation: 0, height: 3 }],
        },
      ],
    };
    ```
  </Step>

  <Step title="Open a session">
    A session builds the geometry and applies your edits. Add its `root` to your scene one time. The root stays the same after each edit.

    ```typescript theme={null}
    export function startBuilding(scene: THREE.Scene): BuildingSession {
      const session = new BuildingSession(emptyBuilding);
      scene.add(session.root);
      return session;
    }
    ```
  </Step>
</Steps>

The scene is still empty, because the storey has no elements. Now [draw a wall](/floorkit/guides/draw-a-wall).

## Change the document

Each element has edit commands. You send a command to the session, and the session changes that element. You keep the session and its undo history.

The guides for slabs, roofs, stairs, columns and rooms add their element with the `add-element` command. This function removes one element with `remove-element`:

```typescript theme={null}
import type { ElementLists } from '@opengeometry/floorkit';

export function removeElement(
  session: BuildingSession,
  list: keyof ElementLists,
  elementId: string,
): void {
  session.apply(
    { kind: 'remove-element', buildingId: 'building', storeyId: 'ground', list, elementId },
    session.revision,
  );
}
```

To load a different building, or to change many elements at one time, change the document and open a new session with it:

```typescript theme={null}
export function replaceBuilding(
  scene: THREE.Scene,
  current: BuildingSession,
  change: (model: BuildingModel) => void,
): BuildingSession {
  const model = current.snapshot();
  change(model);
  const next = new BuildingSession(model);
  scene.remove(current.root);
  current.dispose();
  scene.add(next.root);
  return next;
}
```

* `snapshot()` gives you a copy of the model. You can change the copy safely.
* If the new model is not valid, `new BuildingSession` throws an error. The old session is still in the scene.
* A new session starts with an empty undo history.

Use a command for a change of one element. Use `replaceBuilding` to load or replace a whole building. [Model a mass](/floorkit/guides/model-a-mass) uses this function.

## Close the building

When the user leaves the page, remove the root and release the geometry:

```typescript theme={null}
export function closeBuilding(scene: THREE.Scene, session: BuildingSession): void {
  scene.remove(session.root);
  session.dispose();
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.