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

• Choosing a name

• Implementation

  • Extending the abstract balloon class

  • Extending the Default balloon class

  • Custom balloon styles

• Making the balloon available

• Tests

• 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/ 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.

Extending the abstract balloon class

Here we will discuss how to add a balloon extending the 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. This class has more functionality implemented.

// 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 to pop-a-loon and see it on screen.

Extending the Default balloon class

Extending the Default balloon is a simpler process.

// 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. Further implementation is up to you.

Now you build your class you can make your 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.

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/ module. So we include it in /src/balloons/index.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/ 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/ folder with the name: <name>.md and add there the documentation for your balloon.

Add your balloon spawn chance to the balloon spawn chances and the balloon class to the inheritance tree. Refer to your balloon documentation at the Balloons section.