> For the complete documentation index, see [llms.txt](https://pop-a-loon.gitbook.io/pop-a-loon-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://pop-a-loon.gitbook.io/pop-a-loon-docs/adding-balloon.md).

# Adding a new balloon

Adding a new balloon to the extension is a simple process. In this document we will go over the steps to add a new balloon.

## Table of Contents

* [Table of Contents](#table-of-contents)
* [Choosing a name](#choosing-a-name)
* [Implementation](#implementation)
  * [Extending the abstract balloon class](#extending-the-abstract-balloon-class)
  * [Extending the Default balloon class](#extending-the-default-balloon-class)
  * [Custom balloon styles](#custom-balloon-styles)
* [Making the balloon available](#making-the-balloon-available)
* [Tests](#tests)
* [Documentation](#documentation)

## Choosing a name

The name of the balloon is prefered to be a single word. The name should fit in the text `<name> balloon`. This name will be used in the UI.

## Implementation

Each balloon is it's own class. To add a new balloon, create a new file in the [`/src/balloons/`](https://github.com/SimonStnn/pop-a-loon/blob/main/src/balloons/README.md) directory. The file should be named `<name>.ts`. Make a class in this file and export it. Your new balloon should extend the Balloon class or any other balloon in the [balloon hierarchy](/pop-a-loon-docs/readme.md#inheritance-tree).

### Extending the abstract balloon class

Here we will discuss how to add a balloon extending the [abstract balloon class](/pop-a-loon-docs/readme.md#abstract-balloon-class). This is more complicated as there is less functionality provided in the abstract balloon class.

> \[!TIP] For a simpler implementation refer to [extending the Default balloon class](#extending-the-default-balloon-class). This class has more functionality implemented.

```ts
// example.ts
import Balloon from '@/balloon';

export default class Example extends Balloon {
  public static readonly spawn_chance: number = 0.1;
  public readonly name = 'example';

  public build() {
    // Build the balloon element with the `this.element` div
  }
}
```

Now you build your class you can [make your balloon available](#making-the-balloon-available) to pop-a-loon and see it on screen.

### Extending the Default balloon class

Extending the [Default balloon](/pop-a-loon-docs/balloons/default.md) is a simpler process.

```ts
// example.ts
import Default, { BalloonOptions } from './default';

export default class Example extends Default {
  public static readonly spawn_chance: number = 0.1;
  // @ts-ignore
  public get name(): 'example' {
    return 'example';
  }

  public get options(): BalloonOptions {
    return {
      ...super.options,
      // Override options here
      // e.g. the image url
      imageUrl: 'example.svg',
    };
  }
}
```

In this example the `Example` class extends the `Default` class and overrides the `spawn_chance`, `name` and `options` properties. The options property overrides the image url to `example.svg`. Pop-a-loon will look for this `example.svg` file in the `resources/balloons/example` directory. The image for the balloon doesn't need to be an `svg`, but it is recommended.

You can find what other options you can override in the [default balloon documentation](/pop-a-loon-docs/balloons/default.md). Further implementation is up to you.

Now you build your class you can [make your balloon available](#making-the-balloon-available) to pop-a-loon and see it on screen.

### Custom balloon styles

Implementing a custom balloon may require custom styles. To do this you can add a new css file to your resources folder. To import the css file you can use the `importStylesheet` function from [utils](https://github.com/SimonStnn/pop-a-loon/blob/main/src/utils.ts).

```ts
import { importStylesheet } from '@/utils';

class Example extends Default {
  public build() {
    super.build();
    this.importStylesheet('style.css');
  }
}
```

In this example the `importStylesheet` function is used to import the `style.css` file from the `resources/balloons/example` directory. The `resourceLocation` property is provided by the `Default` class and is the path to the balloon resources.

> The default value for the file name is `'style.css'`. So in this example it can even be excluded.

## Making the balloon available

Now we need to export it from the [`/src/balloons/`](https://github.com/SimonStnn/pop-a-loon/blob/main/src/balloons/README.md) module. So we include it in [`/src/balloons/index.ts`](https://github.com/SimonStnn/pop-a-loon/blob/main/src/balloons/index.ts)

```ts
// index.ts
// ... other balloons
export { default as Example } from './example';
// ... other balloons
```

Balloon exports happen preferable in alphabetical order.

## Tests

Add your balloon test file to the [`/tests/`](https://github.com/SimonStnn/pop-a-loon/blob/main/tests/README.md) folder with the name: `<name>.test.ts` and add the required tests that need to pass for your balloon.

## Documentation

Add your balloon documentation to the [`/docs/balloons/`](https://github.com/SimonStnn/pop-a-loon/blob/main/docs/balloons/README.md) folder with the name: `<name>.md` and add there the documentation for your balloon.

Add your balloon spawn chance to the [balloon spawn chances](/pop-a-loon-docs/readme.md#balloon-spawn-chances) and the balloon class to the [inheritance tree](/pop-a-loon-docs/readme.md#inheritance-tree). Refer to your balloon documentation at the [Balloons section](/pop-a-loon-docs/readme.md#balloons).