> 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).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://pop-a-loon.gitbook.io/pop-a-loon-docs/adding-balloon.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.