Forem: Justin Young

Contributing to Excalibur

Justin Young — Sat, 12 Oct 2024 04:12:04 +0000

This is a submission for the 2024 Hacktoberfest Writing challenge: Contributor Experience

For Hacktoberfest, I created a new Graphic module, called a Nine-Slice, in Excalibur.js. I've spent a couple weeks ironing out the details of the code, proving it out, writing tests, and documenting this contribution. I am going to shed some light on that journey.

I've spent the past couple years using the Excalibur.js game engine to create my games. It has also served as my introduction into contributing to open source projects. We will cover the how and why of contributing to open source projects in this article.

The why behind my contribution

For this contribution, through using the tools in a recent game coding competition, I was in need of a new Graphic type for my game entry. Need being the mother of all innovation, I took a few moments to prototype up a rough component to use in my game, and it was successful. That led me to the belief that others may need something like this so I decided to share it with the community. This demonstrates how new features can be derived by using the tools in their current form and feeling out the opportunity to improve them.

What is the contribution

The Nine-Slice Graphic component is an extension of the standard Graphics library available in Excalibur. This component can allow for a Graphic to be created of any dimensions with a fixed input texture. The component breaks the texture down into 9 separate elements, then redraws the returned graphic to the new dimensions. This allows for users of the component to draw larger graphics without needing to create additional assets.

Let's say your input sprite looks like this:

Well, the 9-slice technique will break up your image into 9 sections, like this:

With the component, you can adjust the margins of the slice boundaries to control how the components are broken up into different pieces.

With these nine pieces, one can create new Graphic images in different dimensions, like this:

The contribution process

After the game coding competition, I cloned a copy of the Excalibur.js repo and created a new local branch. I took my prototype code and refactored it for clarity, so others could easily understand what was happening, including all exported methods, types, and enumerations.

I went to the the discord server for Excalibur and opened up a post in their game dev forum regarding the contribution. This let people review the context of the submission and weigh in on clarity and easy of understanding.

Testing

As is normal with other projects, new features should be accompanied with their own set of unit tests to ensure code quality. This gave me the opportunity to work with Karma, a test runner library for the JS language. I was not really familiar with this library, as I usually use Vitest. But through the documentation and assistance from the community I was able to write enough tests to properly cover my code submission. A big help was looking at other components in the Excalibur project as a guiding template for how the testing could be constructed.

Documentation

Excalibur.js uses docusaurus in their project that allows for markdown files to be displayed. I created a new document page in markdown to explain the usage and configuration of this new graphic so the new docs could be seamlessly integrated into the current documentation scheme of Excalibur.js. Also, quick examples with sample code were provided to improve any onboarding of new users.

Community Engagement

So with the changed source, the updated documents, and the additional unit tests, I submitted the pull request for the change. Then I went back to the discord server to have some discussions and reviews of the changes. There was a lot of good dialogue and ideas on how things could be improved, including a refactoring of the configuration types that allowed for the removal of some //@ts-ignore that I had forgotten to clean up along the way. Other eyes on the documentation led to some iteration of some diagrams to improve clarity.

Conclusion

This is the largest contribution I've made to the core Excalibur code base. I learned a ton over the process of creating the new module, refactoring it for others consumption, writing documentation, and finally the unit tests needed to ensure quality. It feels good to be able to improve the project, and also to give back to a community that has helped me substantially in the past couple years.

For me personally, it helps squash the imposter syndrome that tends to develop when activities like this prove to my self that I am more than capable of making a difference in an open source project. I hope anecdotes like this can help anyone out there that is wondering if they can contribute to projects they enjoy. I strongly urge people to try and get started today! Get Started!!!

About me

I'm a hobbyist developer that has been enamored with game development. I've competed in game jams and coding competitions, and I've really enjoyed engaging with the Excalibur.js community and working with the code base. Come drop me a note!

I'm on twitter at jyoung424242.

My itch.io page: Mookie4242

About Excalibur

ExcaliburJS is a friendly, TypeScript 2D game engine that can produce games for the web. It is free and open source (FOSS), well documented, and has a growing, healthy community of gamedevs working with it and supporting each other. There is a great discord channel for it JOIN HERE, for questions and inquiries. Check it out!!!

One-Byte Explainer: Excalibur.JS

Justin Young — Sun, 29 Sep 2024 16:56:25 +0000

This is a submission for the Web Game Challenge: One Byte Explainer

Explainer

Excalibur.JS is a TypeScript based, 2d game engine for the web! Its free and open source, type safe, extensively documented, and is intended and designed for cross-platform gaming! It has a growing, friendly community that is super supportive and responsive.

Link to Excalibur.js

Excalibur Discord

Vision

The goal is to make it easier for you to create 2D HTML/JS games, whether you're new to game development or you're an experienced game developer. We take care of all of the boilerplate engine code, cross-platform targeting, and more! Use as much or as little as you need!

Design Philosophy

Excalibur aims to be the best 2D game development experience for the web.
Excalibur is flexible with sensible defaults.
Excalibur is a "batteries included" game engine, you can just do the things you want.

Features included

Physics
Scenes
Particle Systems
Resource Loading
Chrome Dev Tools Extension for debugging
Strongly Typed with excellent autocomplete
Built in ECS system
Tilemap support with plug-ins for LDTK, Tiled, and SpriteFusion
Easily imports in Aseprite native files with the Aseprite plug-in
Many samples available to assist with onboarding
plus much, much more...

Alien Waves

Justin Young — Sat, 28 Sep 2024 17:06:23 +0000

This is a submission for the Web Game Challenge, Build a Game: Alien Edition

What I Built

This is a tower defense game based on the theme of Aliens. Your ship is stranded on an unknown alien planet and you must defend yourself from the waves of aliens that attack your ship!

You can click or touch the playing field to place defense turrets on the level to deal with the waves of Aliens that spawn.

Each level will increase in difficulty, so you really need to be wise regarding how you balance your wave funds between cheap turrets and the expensive turrets.

There are no AI generated assets in this game.

Demo

Web Game on Itch.io

Journey

This game is made using Excalibur.js, a free and open source Typescript 2d game engine. Its a solo developed game. I am a member of the Excalibur community, and I have contributed to the Excalibur.js project.

Excalibur Discord Invite

The GitHub Project is located here: GitHub Repo

Biggest Lesson Learned: I have a long way to go to learn real UI/UX skills. But this is a journey, not a destination. ;)

Techniques implemented in this project

Finite State Machines: This uses a FSM library I wrote to use with Excalibur.js. A state machine was used for:

Wave Management
Unit animations

Screen Elements: This is a special type of entity in Excalibur.js. Usually, I use a UI-binding library to place a DOM layer over my game canvas. This is my first usage of the built-in UI entities in Excalibur.js.

9-slice UI component: I created a reusable Graphic for Excalibur.js to create 'panels' based on a base sprite. This allows for a standard sprite tile to be 'split' into 9 sections and either stretched or tiled appropriate to create custom panels.

Shaders: Not a massive implementation of shaders, but I use a base texture sprite for the laser blasts and then use a tinting shader to distinguish between each type of blast.

Re-usable components: I was pretty happy with the Health Bar that i created as a component for each entity, and after a few iterations, i was able to make it configurable upon each units Initialization. This saved a lot of time.

Signals: Taking inspiration from Godot's Signals, I created a custom signals library that is essentially a pub/sub system to create a event bus of custom JS events. An example of this is the GameOver signal, which each entity subscribes to, and when the game is over, that signal clears all existing entities from the board.

Roadmapped Development

Being a 10 day competition, the original intention was to hit a MVP level submission, which I was able to accomplish about 7-8 days into it. Over past 2 days of competition, I've been adding additional content to the game. This included the development of a 2nd turret, and a 2nd Enemy type. Other ideas for future features include:

Power ups dropped by enemies
More enemies, more turrets
Add options screen to control music and SFX better

Asset Attributions

The alien sprites were created with the Kenney's Creature Mixer tool.

The blast sprites from the turrets use particle sprites from Kenney's Particle Pack.

The ship is from Kenney's Ship Mixer tool.

The turrets I drew in Aseprite.

Sound Effects are generated with the Excalibur JSFXR plugin which I created.

Background Music is using a Chiptune generator I created from a fork of Vitling's Autotracker

Level texture was used from Itch.io texture pack Texture Pack from user FlakDeau19... special thanks to them for their VERY permission license.

Component Based Architecture in Peasy-UI: Part 5 of the Peasy-UI Series

Justin Young — Sun, 15 Sep 2024 15:03:52 +0000

Table of Contents

Introduction
Component Based Design
Registering Single File Components with Peasy
- JavaScript (TypeScript) Single File Component
- HTML Single File Component
Demo Application
- Label Component
- Button Component
Demo Component Implementation
- AppUI Class
  - Rendering Template
  - Class properties as State
More information
Conclusion

Introduction

Today we are going to dive into the final layer of the Peasy-UI library. We are going to do a deep dive into how to use Peasy-UI to build re-usable UI components. This will assist with building modular, scalable, re-usable code blocks and simplify one's code architecture.

In this article, we will review the benefits of component based architecture, the different component features of the Peasy-UI library, specifically single-file components that can be done in JavaScript or HTML, and then we will wrap up with a dive into a demo application to reinforce many of the ideas introduced today.

If you missed the introduction article for Peasy-UI, you can read it here, and it can provide the overview for the library.

Component Based Design

Larger applications need to be architected in a manner that keeps the code base clean and lean, in a manner where duplicate code isn't being used. One strategy to help with a "don't repeat yourself" approach is to design your front-end in modular manner, and design that structure to re-use components. Component based architecture provides increased flexibility, improved maintainability, increased readability, and also improves organization of a code base.

Registering Single File Components with Peasy

Peasy UI makes it possible to create both JavaScript and HTML single file components and import them for use in the app, without the need of a build step. You also can use this with Typescript when you bundle with your preferred bundling tool that transpiles your TS files into JS. Peasy-UI only needs a template property in order to render a component, but for Peasy-UI to instantiate and render components based on a template object/class and (optionally) data, the template object/class needs:

a template property
a create method (which gets invoked with designated data model)
to be known to the parent model either as a property or through the use of the UI.register method

JavaScript (TypeScript) Single File Component

There are two ways of fulfilling the 3rd requirement above, providing the component to the parent model. You can either use UI.register() method, or include the exported class into the parent data model yourself. For this example, we will use the UI.register(), but in the demo application below, we demonstrate the other method of meeting this requirement.

// list-item.js

import { UI } from "https://cdn.skypack.dev/@peasy-lib/peasy-ui";

export class ListItem {
  static template = "<span>Hello, ${name}!</span>";

  constructor(name) {
    this.name = name;
  }
  static create(state) {
    return new ListItem(state.name);
  }
}
UI.register("ListItem", ListItem);

Then we can import it into our HTML and implement it, the below example demonstrates how to bypass the build step requirement, by way of CDN import.

<!-- index.html -->
<body>
  <template id="sfc-app">
    <div>
      <div pui="name <=* names"><list-item pui="ListItem === name"></list-item>
    </div>
  </template>

  <script type="module">
    import { UI } from "https://cdn.skypack.dev/@peasy-lib/peasy-ui";
    import { ListItem } from './list-item.js';

    class SFCApp {
      names = [{ name: 'World' }, { name: 'everyone' }];
    }

    UI.create(document.body, '#sfc-app', new SFCApp());
  </script>

HTML Single File Component

You can also create your single file components using the HTML format as well. The one benefit from this approach is that your template html doesn't have to be a string literal anymore, and can be use any IDE syntax highlighting or autocomplete as a useful tool.

<!-- list-item.html -->
<style>
  list-item {
    color: gold;
  }
</style>

<template id="list-item">
  <span>Hello, ${name}!</span>
</template>

<script type="module">
  import { UI } from "https://cdn.skypack.dev/@peasy-lib/peasy-ui";

  export class ListItem {
    static template = document.querySelector("#list-item"); // This can also be a string

    constructor(name) {
      this.name = name;
    }

    static create(state) {
      return new ListItem(state.name);
    }
  }
  UI.register("ListItem", ListItem); // Is necessary for HTML single file components
</script>

Since HTML imports aren't here (yet), Peasy UI uses the UI.import() and UI.ready() methods to support HTML single file components. From a templating perspective, there's no difference between JavaScript and HTML single file components and the two types can co-exist and be used in the same app. So the implementation details of the HTML component is:

<!-- index.html -->
<head>
  <script type="module">
    import { UI } from "https://cdn.skypack.dev/@peasy-lib/peasy-ui";

    UI.initialize(); // UI.initialize is necessary with HTML components and needs to be in a head in top file
  </script>
</head>

<body>
  <template id="sfc-app">
    <div>
      <div pui="name <=* names"><list-item pui="ListItem === name"></list-item></div>
    </div>
  </template>

  <script type="module">
    import { UI } from "https://cdn.skypack.dev/@peasy-lib/peasy-ui";

    UI.import("./list-item.html");

    class SFCApp {
      names = [{ name: "World" }, { name: "everyone" }];
    }

    await UI.ready(); // Awaiting UI.ready is necessary with HTML imports
    UI.create(document.body, "#sfc-app", new SFCApp());
  </script>
</body>

Going forward, we will dig into a small demonstration app, but it will be using Typescript for its components, and is using Vite as a build tool and bundler.

Demo Application

Link to application GitHub repo

Link to demo application

The demo that's shown here is a very simple app to provide some context on how the Peasy-UI library's component features are utilized.

This demo features two component types, a Label and a Button. The button component is used twice, and is passed different parameters to control not only its behavior but its aesthetic.

Label Component

// ./src/components/label.ts

export type LabelState = {
  count: number;
  className: string;
};

export class Label {
  // HTML template
  // this is the HTML that get's rendered for the component - required for Peasy-UI components
  public static template = `
    <style>
      .label_Component {
          font-size: 3em;
          color: whitesmoke;
      }
    </style>
    <div class="label_Component \${className}">\${count}</div>
  `;

  // internal method that manipulates state
  increment {
    this.count++;
  };

  // internal method that manipulates state
  decrement {
    if (this.count > 0) this.count--;
  };

  // constructor that also defines the component state variables by the public keyword
  constructor(public count: number, public className: string) {}

  // static method that creates an instance of the class - required for Peasy-UI components
  // but this is all under the hood, it becomes a UIView in your data model
  static create(state: LabelState) {
    return new Label(state.count, state.className);
  }
}

The Label is a simple component that displays and controls the count value within its own DOM element. In the template literal you can see that it owns its own styling, plus its own DOM element, which has two Peasy-UI bindings in it. First, the public classname is used to add a secondary CSS class to a label if necessary, in this example it isn't used, but added to show that capability. The second binding is the public count value which is bound to the component div element.

There are two internal methods, increment() and decrement(), that are used to control the count state, and these provide external access for other components to call to manipulate the count value. This removes the need to modify the count value directly, and let's the component manage that.

Also note the create method, which is required functionality to be a Peasy-UI component. Also I define the incoming state, since I'm using Typescript, to improve the development experience on the parent side to ensure that I'm using the component properly. This isn't required, but a nice to have feature.

All aspects of the label's appearance and behaviors are captured in this one file.

Button Component

/// ./src/components/button.ts
export type ButtonState = {
  buttonText: string;
  className: string;
  buttonClickHandler: (event: Event, model: any, elem: HTMLElement) => void;
};

export class Button {
  // HTML template
  // this is the HTML that get's rendered for the component - required for Peasy-UI components
  public static template = `
    <style>
      .button_Component {
          font-size: 1em;
          border-radius: 10px;
          border: 0px;
          width: 60px;
          height: 25px;
          margin: 5px;
          font-weight: bold;
          color: #111111;
          background-color: whitesmoke;
      }

      .button_Component:active {
        -webkit-box-shadow: inset 0px 0px 5px #c1c1c1;
        -moz-box-shadow: inset 0px 0px 5px #c1c1c1;
        box-shadow: inset 0px 0px 5px #c1c1c1;
        outline: none;
      }

      .up {
        color: whitesmoke;
        background-color: green;
      }

      .down {
        color: whitesmoke;
        background-color: red;
      }

    </style>
    <button class="button_Component \${className}"  \${click@=>buttonClickHandler}">\${buttonText}</button>
  `;

  // constructor that also defines the component state variables by the public keyword
  constructor(
    public buttonText: string,
    public className: string,
    public buttonClickHandler: (event: Event, model: any, elem: HTMLElement) => void
  ) {}

  // static method that creates an instance of the class - required for Peasy-UI components
  // but this is all under the hood, it becomes a UIView in your data model
  static create(state: ButtonState) {
    return new Button(state.buttonText, state.className, state.buttonClickHandler);
  }
}

Now the button component has a little more going on than the Label component. We have similar aspects of the Label component, such as the create method, component level styling in the template literal, plus all the bindings that we have for a button. One of those bindings is unique, in that the button event callback is passed into the component so that we can use this button for different processes. This is using the event binding on the 'click' event on the DOM element. The other bindings are the button label and adding the classname to control different styles.

Demo Component Implementation

AppUI Class

// ./src/ui.ts

import { Label, LabelState } from "./components/label";
import { Button, ButtonState } from "./components/button";
import { UIView } from "@peasy-lib/peasy-ui";

export class AppUI {
  public static template = `
<div>
    <div class="container">

        <div class="label_container">
          <!-- Using the Peasy-UI Component here for a Label-->
          <\${Label:labelView=== counterState}>
        </div>

        <div class="button_container">
          <!-- Creating two instances of the Peasy-UI Components here for buttons-->
          <\${Button === upButtonState}>
          <\${Button === downButtonState}>
        </div>

    </div>
</div>`;

  // Class Properties as State below
  // ↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓

  // this is me fulfilling that 3rd requirement w/o the UI.register() method
  public Button = Button;
  public Label = Label;

  // this is the assigned 'instance' of the Label component (as a UIView)
  labelView: UIView | undefined = undefined;

  // This is the state 'props' that are passed into the Label component
  counterState: LabelState = { count: 0, className: "" };

  // This is the state 'props' that are passed into each button component
  upButtonState: ButtonState = {
    buttonText: "Up",
    className: "up",
    buttonClickHandler: () => {
      //reference to the internal method in the Label class
      this.labelView!.model.increment();
    },
  };

  downButtonState: ButtonState = {
    buttonText: "Down",
    className: "down",
    buttonClickHandler: () => {
      //reference to the internal method in the Label class
      this.labelView!.model.decrement();
    },
  };
}

So with any Peasy-UI project, we have a data model that represent the application state that Peasy uses. In this implementation, we are using the AppUI class to provide that data model. The properties of the class becomes the active 'State' for the data model. Let's go through this section by section.

Rendering Template

public static template ="...";

I like to define the template at the top of my class but that isn't necessary, its developer preference and just a habit of mine. This is the parent string template that is provided into the UIView.Create() method for rendering. This provides the HTML content that Peasy-UI will render inside the target element, in this example its document.body. Here we can point out the bindings for the Peasy-UI components.

Let us look at the two different types of Component bindings here. Let's take the Label binding first.

<\${Label:labelView=== counterState}>

The three important ideas passed here are the class of Component: Label, the UIView (instance) assignment :labelView, and the state object provided: counterState. All three of these are used with the === binding tag. This essentially states that we are creating a View of the Label class, using the counterState object as a property to pass into the create method, and that the returning View of the class should be saved by reference in the labelView value. Since we are using the instance (View) value, we can then have access to all the internals of the class just like any other JS class can.

<\${Button === upButtonState}>
<\${Button === downButtonState}>

Now there are just two different aspects of the Button binding. First, we are using two instances of the binding, but are passing two different state objects, this demonstrates the 're-usability' of the component. As a reminder, this even includes us passing the event callback into the component so its behavior is provided to it.

Secondly, we are not in need of the View of the component classes, so we are not binding the return value to anything.

Class properties as State

  // this is me fulfilling that 3rd requirement w/o the UI.register() method
  public Button = Button;
  public Label = Label;

The first two things declared in the data model are the actual component classes. This provides Peasy-UI access to the class components, and when a template binding calls these out, it uses the create method on each class to instantiate each component. This fulfills that 3rd requirement for a Peasy-UI component.

// this is the assigned 'instance' of the Label component as a UIView
  labelView: UIView | undefined = undefined;

labelView is the UIView returned when Peasy-UI uses the create method to create an instance of the Label class, then converts it to a UIView representing a Label class that is created, this gives us access to the two methods we will use to control the count on the label. We will see later in the template section how the binding to this works. Its important to note, that i call out labelView as either a UIView | undefined, and this is because it IS undefined until the UIView.create().attached property in the main.ts call resolves its promise. This is a means to appease Typescript type checking, but it is important to note and understand that it is undefined until the View is attached.

// main.ts
// Peasy-UI method for creating a View and attaching to DOM
await UI.create(document.body, new AppUI(), AppUI.template).attached;

It is possible to not use the attached property, but there is a risk of attempting to render something from the data model that hasn't been evaluated yet, and this pattern prevents that from occurring. Once the view is attached to the DOM, then all undefined values in the data model will be evaluated to their intended states.

// This is the state 'props' that are passed into the Label component
counterState: LabelState = { count: 0, className: "" };

// This is the state 'props' that are passed into each button component
upButtonState: ButtonState = {
  buttonText: "Up",
  className: "up",
  buttonClickHandler: () => {
    //reference to the internal method in the Label class
    this.labelView!.model.increment();
  },
};

downButtonState: ButtonState = {
  buttonText: "Down",
  className: "down",
  buttonClickHandler: () => {
    //reference to the internal method in the Label class
    this.labelView!.model.decrement();
  },
};

counterState, upButtonState, and downButtonState are all objects that pass the default states into each component. Special note here is that as a part of the Button states, we are passing the event callback as state into the components, so we can re-use the components and control their behaviors. Since they are JS objects, and passed as reference, you can modify these values directly and it will change the values inside the component classes.

More information

More information can be found in the github repo for Peasy-Lib, you also will find all the other companion packages there too. Also, Peasy has a Discord server where we hang out and discuss Peasy and help each other out.

The author's twitter: Here

The author's itch: Here

Peasy-UI Github Repo: Here

Peasy Discord Server: Here

Conclusion

In summary, we looked at the different approaches that can be used to build Peasy-UI components, including single-file HTML components, or JS/TS based components. We looked at how you can use Peasy-UI components without a build step.

We also reviewed a demo application that demonstrates some of the component features and implementation details. This includes using both the Class and Instances of a component, and using different state objects to re-use a component with different behaviors.

We also walked through using a JS Class as the basis for creating the UIView for Peasy-UI that includes both the string template literal, and uses the class properties as the data model state.

The big take aways from a component based architecture is modular design, cleaner code, and being able to reuse common components to improve maintainability of your code base!

Controlling CSS with Peasy-UI: Part 4 of the Peasy-UI Series

Justin Young — Mon, 02 Sep 2024 03:40:04 +0000

Table of Contents

Introduction
Binding CSS Properties
- Internal CSS
- Inline CSS
The Three Helpers
- pui-adding
- pui-removing
- Show/Hide Example
- pui-moving
Conclusion
More information

Introduction

In my latest installment of the Peasy-UI library series we are going to dive another layer deeper. In this entry, we will cover how you can use both internal CSS and inline CSS bindings with Peasy-UI. We also are going cover the CSS helper classes that are made available using Peasy to assist with animations. We will dig into each of the three classes that are available, and we can cover how they can be used in your template and bind elements to these helper classes.

If you missed the introduction article for Peasy-UI, you can read it here, and it can provide the overview for the library, and even introduces upcoming topics in the series.

Binding CSS Properties

In this section, let's cover different strategies of using Peasy-UI's bindings with CSS.

Internal CSS

When I am binding style properties for a Peasy-UI component or small application, my primary approach is to use the standards <style></style> block above my html that I am using. Let's take a look at a quick example.

In this example I have a toggle button, which when clicked is transitioning the elements position back and forth. The other button functions will be reviewed in their designated sections later.

In my DOM template:

...
<button \${click@=>toggle}>Toggle</button>
...
<test-element></test-element>
...

My CSS for this:

test-element {
  position: fixed;
  top: 50%;
  left: 50%;
  width: 50px;
  aspect-ratio: 1/1;
  background-color: whitesmoke;
  border-radius: 50%;
  transform: translate(-\${leftPercent}px, 150px);
  transition: transform 0.9s ease-in-out, scale 0.9s ease-in-out;
  scale: 1;
}

In my data model, our logic:

const model = {
  toggleFlag: true,
  leftPercent: 0,
  toggle: (_element: HTMLElement, model: any) => {
    if (model.toggleFlag) model.leftPercent = 100;
    else model.leftPercent = 0;
    model.toggleFlag = !model.toggleFlag;
  },
};

When the toggle method is fired by clicking the button, we use the model.toggleFlag to track our toggle state, and also set the model.leftPercent property to different values. This is the first way I bind CSS properties in Peasy-UI. Another trick I use is I can change the color string of CSS property to transition colors as well. As a general reminder, the first parameter of a Peasy-UI callback is the parent element of the event, and if I'm not using it in the current method, I designate it with the _ prefix. For more details on how Peasy-UI binds event callbacks, a prior article addresses it in a deeper context: Event Binding.

test-element {
  ...
  background-color: \${colorString};
  ...
}

  const model = {
    ...
    colorString: "whitesmoke",
    ...
  };

I can just change the string to other css colorstrings to change the elements color, or you can use a hexstring.

Inline CSS

For more complicated CSS manipulation, sometimes I have added bindings to inline class attributes on elements. That way I can bind a string in the data model, and can control specifically what CSS classes I want active on an element. Let's take a look at a quick example.

In this demonstration you see the test element is toggled on its scale property. Let's take a quick look at how I am accomplishing this.

In my DOM template:

...
<button \${click@=>inlinetoggle}>Inline Toggle</button>
...
<test-element class="\${testClassName}"></test-element>
...

my css for this:

test-element {
  position: fixed;
  top: 50%;
  left: 50%;
  width: 50px;
  aspect-ratio: 1/1;
  background-color: whitesmoke;
  border-radius: 50%;
  transform: translate(-\${leftPercent}px, 150px);
  transition: transform 0.9s ease-in-out, scale 0.9s ease-in-out;
  scale: 1;
}

.scaleTestElement {
  scale: 1.5;
}

and in my data model:

export const model = {
  ...
  inlinetoggleFlag: false,
  testClassName: "",
  ...
  inlinetoggle: (_element: HTMLElement, model: any) => {
    if (model.inlinetoggleFlag)  model.testClassName = "";
    else  model.testClassName = "scaleTestElement";
    model.inlinetoggleFlag = !model.inlinetoggleFlag;
  },
};

Let's breakdown what aspects are highlighted here. Let's start with the toggle button being used to trigger the change, that's a simple button element with a click event binding the inlinetoggle method in the data model to the button. When that method is called, the data model uses a toggle flag, model.inlinetoggleFlag to track a toggle state, and it also changes the model.testClassName string. In the template DOM, the test-element has a class attribute with a string binding in it. When you update the string in the data model, the new class gets added to the element, changing the scale property. The transition property of the element covers the scale property as well.

The Three Helpers

This section will describe the functionality and implementation details of three built-in CSS helper classes that are used in Peasy-UI. This features happen natively regardless if they are taken advantage of or not. These three helpers are: pui-adding, pui-removing, and pui-moving. These are CSS class names added to elements that are being manipulated by Peasy-UI, and are available to be leveraged for managing transitions.

pui adding

The pui-adding CSS class is added to an element when it transitions from not rendered to rendered. This can happen in a couple scenarios. If you are adding an element to a list that's rendered with the <=* binding, then that new element receives the pui-adding class. Another means of adding an element is by using the rendering binding === or !==. To review the available bindings for Peasy-UI, you can reference this article on the bindings here:Bindings and Templates: Part 2 of the Peasy-UI series

The duration of the CSS class being adding is until any transitions tied to pui-adding class is complete. Let's take a deeper look at this.

const model = {
  isDivShowing: false,
};

const template = `

<style>
    .child{
      opacity: 1;
      transition: opacity 1.0s;
    }

    .child.pui-adding{
      opacity: 0;
    }
</style>

<div class="parent">
  <div class="child" \#{===isDivShowing}>
      Hello World
  </div>
</div>
`;

UI.create(document.body, model, template);

In this example what you will see is that when you set model.isDivShowing to true, Peasy-UI will add the element to the DOM, starting with the pui-addding class. The pui-adding class will automatically be removed from the element upon the completion of the 1 second CSS transition that is set for the opacity property.

pui removing

You will see that the pui-removing class helper is the opposite of pui-adding.

The pui-removing CSS class is added to an element when it transitions from rendered to not rendered. This can happen in a couple scenarios. If you are removing an element from a list that's rendered with the <=* binding, then that element which is being removed receives the pui-removing CSS class. Another means of removing an element is by using the rendering binding === or !==.

The duration of the class removing is until any transitions tied to pui-removing class is complete. Let's take a deeper look at this.

const model = {
  isDivShowing: true,
};

const template = `

<style>
    .child{
      opacity: 1;
      transition: opacity 1.0s;
    }

    .child.pui-removing{
      opacity: 0;
    }
</style>

<div class="parent">
  <div class="child" \#{===isDivShowing}>
      Hello World
  </div>
</div>
`;

UI.create(document.body, model, template);

In this example, what you will see is that when you set model.isDivShowing to false, Peasy-UI will add the pui-removing class to the element prior to transitioning the element from the DOM. The pui-removing class will remain on the element upon the completion of the 1 second CSS transition that is set for the opacity property, of which the entire element is removed from the DOM completely.

Show Hide Example

In this example we are working with a DOM template that renders this:

<div>
    <div class="controls">
        <button \${click@=>hide}>Hide</button>
        <button \${click@=>show}>Show</button>
        <button \${click@=>move}>Move</button>
    </div>
    <element-container>
        <inner-element \${el<=*elements}>
            \${el.id}
        </inner-element>
    </element-container>
</div>

In this example, we have replaced standard

elements with more custom names to assist in clarity. and are just elements in practice.

You can see the inner-element div has a list binding that takes the elements array and lists out an inner-element for each item in the list, and places the .id property of each object into the content for the element.

For the sake of this quick demo, we are using a fixed data model: (showing only the elements array)

export const model = {
  elements: [
    {
      id: 1,
    },
    {
      id: 2,
    },
    {
      id: 3,
    },
  ],
  //... click bindings below

What is important here is the CSS styling we added to the rendered template

inner-element {
  ...
  /*other properties that aren't relevant above*/
  transition: opacity 0.9s, background-color 1.2s;
  opacity: 1;
  background-color: whitesmoke;
}

inner-element.pui-adding {
  opacity: 0;
}

inner-element.pui-removing {
  opacity: 0;
}

In the click handlers for the Hide and Show buttons, we are removing and adding the elements from the array. Nothing fancy, but it exercises how Peasy-UI uses the helper classes to manage the CSS transitions. Either helper CSS classes are added, and then the opacity transition of 0.9 seconds starts, then the class is removed. This is how you can use Peasy-UI to manage element transitions.

pui moving

The pui-moving CSS class is added to an element when the element is a part of a list or array, and moves indexes within that list.

The duration of the class adding is until any transitions tied to pui-moving class is complete. Let's take a quick look at this.

In this example, we will call a function that changes the order in the list of elements. When we change the index positions, the pui-moving class will be added to the element. We are using the .pui-moving class to change the elements red that are moving, and this transition happens over time. After the transition period, the array is rendered with the updated order to the DOM.

Our DOM template:

<button \${click@=>move}>Move</button>
<element-container>
  <inner-element \${el<="*elements}"> \${el.id} </inner-element>
</element-container>

Our CSS:

inner-element {
  width: 100px;
  aspect-ratio: 1/1;
  background-color: whitesmoke;
  border-radius: 50%;
  color: black;
  display: flex;
  justify-content: center;
  align-items: center;
  font-size: 24px;
  transition: opacity 0.9s, background-color 1.2s, left 0.9s;
  opacity: 1;
  scale: 1;
  left: 0px;
}

inner-element.pui-moving {
  background-color: red;
}

and our DOM model logic:

const model ={
  elements: [...],
   move: (_element: HTMLElement, model: any) => {
    if (model.elements.length > 0) {
      if (model.elements[0].id === 1) {
        moveElement(model.elements, 0, 2);
      } else {
        moveElement(model.elements, 2, 0);
      }
    }
  },
};

function moveElement(array: any[], fromIndex: number, toIndex: number) {
  const element = array.splice(fromIndex, 1)[0]; 
  array.splice(toIndex, 0, element); position
}

We have a button element that triggers a toggle of sorts, but only based on the content of the elements array in the data model. If the element in the zero index position has an id of 1, then we move that element to the 3rd position, index 2. Otherwise, we move the element from index 2 into index 0. One observation that can be made, is that moving one element actually forces all the elements in this example to move, therefore, all three elements get the pui-moving class added.

Conclusion

Our focus in this article in the Peasy-UI series is CSS. We took a look into internal and inline CSS binding, with code samples and an example. Next we discussed the three CSS helper classes that are available to use, pui-adding, pui-removing, and pui-moving. Our examples in this article are straightforward, but one can see how they can be applied to provide a sophisticated level of control of the DOM.

In our next entry, we will dig into the most complicated concept of Peasy-UI, and break it down into smaller bites: using Peasy-UI to make re-usable components.

More information

More information can be found in the GitHub repo for Peasy-Lib, you also will find all the other companion packages there too. Also, Peasy has a Discord server where we hang out and discuss Peasy and help each other out.

The author's twitter: Here

The author's itch: Here

Peasy-UI Github Repo: Here

Peasy Discord Server: Here

Binding Events for the DOM: Part 3 of the Peasy-UI Series

Justin Young — Mon, 12 Aug 2024 13:54:44 +0000

Table of Contents

Introduction
Bindings for events
Callback Params
- Event
- Data Model
- Target Element
- Event String
- Parent Data Object
More information
Conclusion

Introduction

Today we are going to dive a layer deeper into the Peasy-UI library. We are going to do a deep dive into binding strategies for user events in the DOM. User events in the DOM are particularly targeted towards how the user of the app will interact with it. This can be touch interfaces, mouse pointers and drag, typing into fields, etc...

If you missed the introduction article for Peasy-UI, you can read it here, and it can provide the overview for the library, and even introduces upcoming topics in the series.

Bindings for events

Let's dig into the mechanics of capturing user events from the DOM. If want to render a drop down select input, or a button? Peasy-UI gives you access to mapping the event listeners automatically and tying them into the data model.

BINDING: ${ event @=> callbackName}

Buttons provide easy examples for this, but all DOM events can be used.

const model = {
  clickHandler: () => {
    window.alert("I got clicked");
  },
};

const template = `
<div>
    <button \${click @=> clickHandler}> Click Me! </button>
</div>
`;

You can bind any HTML DOM event, such as change, input, click, mouseenter, etc... as an event binding, and then you provide the 'handler' callback which exists IN the data model.

Callback Params

Peasy passes 5 standard parameters into the handler for your convenience.

Event

The first parameter is the HTMLEvent that actually is fired.

const model = {
  clickHandler: (evt: HTMLEvent) => {
    console.log(evt);
  },
};

const template = `
<div>
    <button \${click @=> clickHandler}>Click Me!</button>
</div>
`;

Data Model

The second parameter is the 'localized' data model that is bound to the element. This CAN be tricky, because depending on your nesting of elements, it maybe be a localized data model for just that element, or if it is a top level binding, it will be the standard data model. When we dig into lists and arrays and how Peasy renders them, we will discuss this localized data model and how it can be used.

const model = {
  isA: true;
  numClicks: 0;
  clickHandler: (evt: HTMLEvent, model: any) => {
    console.log(model);
  },
};

const template = `
<div>
    <button \${click @=> clickHandler}>Click Me</button>
</div>
`;

// will log --> > {isA: true, numclicks: 0, clickHandler: f}

Target Element

The third parameter is the target element that fired the event, so you can access any attributes nested in the element or its value.

const model = {
  clickHandler: (evt: HTMLEvent, model: any, elem: HTMLElement) => {
    console.log(elem);
  },
};

const template = `
<div>
    <button \${click @=> clickHandler}>Click Me</button>
</div>
`;

Event String

The fourth element is the string representation of the event, such as 'click' or 'change' and this helps in case you bind multiple events to the same callback, you can distinguish which event triggered this callback.

const model = {
  clickHandler: (evt: HTMLEvent, model: any, elem: HTMLElement, eStr: string) => {
    console.log(eStr);
  },
};

const template = `
<div>
    <button \${click @=> clickHandler} \${mouseenter @=> clickHandler}>Click Me</button>
</div>
`;

Parent Data Object

The final parameter is the overarching data model. Inside this object, regardless of how nested your binding is, will be an object that contains the model property, and you can navigate that object to have access to ANY property in the data model. This becomes very important when you start using arrays and lists for rendering elements.

const model = {
  clickHandler: (evt: HTMLEvent, model: any, elem: HTMLElement, eStr: string, obj: any) => {
    console.log(obj);
  },
};

const template = `
<div>
    <button \${click @=> clickHandler}>Click Me</button>
</div>
`;

// will log out -->    > {$model:{...}}

More information

The author's twitter: Here

The author's itch: Here

Github Repo: Here

Discord Server: Here

Conclusion

In this entry of the Peasy-UI library breakdown we dove deeper into how user input DOM events can be bound into the data model so Peasy-UI can create and manage the event listeners for you. One unique aspect of the event handlers in the data model is the callback parameters that are pulled into the callback by default, including: the event object, the data models, the event string, and the HTML element itself. This gives the developer a unique set of tools to perform very customizable events, but with a favorable developer experience. Our next article will address some of the helper CSS classes that come with Peasy-UI out of the box.

Bindings and Templates: Part 2 of the Peasy-UI series

Justin Young — Sun, 28 Jul 2024 04:03:45 +0000

Table of Contents

Introduction
Bindings and the Template
Text Bindings
- Basic Binding
- Conditional Boolean Text Binding
- One-time Text bindings
Attribute Bindings
- Bindings for element attributes
- Bindings for events
- Binding whole elements to data model
- Binding for Rendering
- Binding for Arrays
- Bindings for Components
Getters
More information
Conclusion

Introduction

Today we are going to dive a layer deeper into the Peasy-UI library. We are going to explain the different types of bindings that are available in the library, and how you can incorporate them into the string literal template that you provide to the library to be rendered to the DOM. For this article all examples are provided using TypeScript, but the library works with vanilla JavaScript perfectly fine.

If you missed the introduction article for Peasy-UI, you can read it
here, and it can provide the overview for the library, and even introduces upcoming topics in the series.

Bindings and the Template

I quick recap of what bindings are, what the template is, and how they work with the library to give you control of what gets rendered to the DOM.

Peasy-UI is a library that injects content into DOM elements that you specify. The content that gets injected is dictated by a string literal template that provides HTML markup that represents the content to be injected.

const template = `
  <div> Render Me </div>
  <button> Click </button>
`;

This is an example of the string literal template that you pass to Peasy-UI and it will render it into the targeted DOM element.

Bindings provide a means to control that template dynamically. For example, let's do a Hello World example.

const model = {
  name: "Bob",
};

const template = `
<div>
    Hello: \${name}!!!!
</div>
`;

await UI.create(document.body, model, template).attached;

This code creates the data store (model), that is bound to the html in the string literal template. UI.create() takes the model, template, and the targeted DOM element to inject into as parameters. In your JavaScript code, you can change model.name to whatever string you'd like, and it will dynamically re-render the new text into the DOM. Side note: the await in the UI.create() method pauses the execution of subsequent logic until Peasy-UI attaches the content into the DOM. This way you can prevent trying to make changes or access DOM content that isn't rendered yet.

Text bindings

There are two types of bindings in Peasy-UI, text bindings and attribute bindings, and we will explore both types. One thing to note is that since we are providing a string literal to Peasy-UI, we use the backslash escape character to designate it as a binding.

Basic binding

The most basic binding is simply injecting data into the DOM as text. The Hello World above is a prime example of this. Use cases for this binding can include manipulating the inner text or inner HTML content inside a DOM element, such as changing a name. I've also used this for changing CSS properties inside a CSS string.

BINDING: ${propertyName}

As in the example above, we can use this:

const model = {
  name: "Bob",
};

const template = `
<div>
    Hello: \${name}!!!!
</div>
`;

The binding maps the 'name' property to the tag in the HTML and replaces name with the name content from the model.

Conditional boolean text binding

In order to control if a binding is active, we can leverage some conditional bindings.

BINDING: ${'value' = propertyName}

BINDING: ${'value' ! propertyName}

An example of this would be:

const model = {
  darkMode: true,
};

const template = `
<div>
    I am using \${'Dark mode' = darkMode} \${'Light mode' ! darkMode} now!
</div>
`;

Based on the truthy status of the darkMode property in the model, different text renders. If true, the div will say I am using Dark mode now! and if its set to false, it will render I am using Light mode now!.

One-time text bindings

The previous bindings get constantly evaluated with respect to RequestAnimationFrame(). However, sometimes you may only want to evaluate it one-time, like on initialization. Peasy-UI provides one-time bindings.

BINDING: ${|'value' = prop}

BINDING: ${|'value' ! prop}

The same example above can be reused, the only difference is that the evaluation of the darkMode property will only be done on the first rendering cycle. Please take note of the pipe character in the binding, as that is what designates it as a one-time binding.

Attribute Bindings

Attribute bindings use either \${ } or the pui attribute within an element tag to affect the behaviour of the element. For the sake of this article we will continue using the \${ } nomenclature. We will explore the different methods of assigning bindings in a future article.

Bindings for element attributes

Peasy-UI gives us the power to access element attributes and allows us to monitor and control those values easily.

There are four basic element attribute bindings:

BINDING: ${attribute <== propertyName} bind in one direction from the model to the binding

BINDING: ${attribute <=| propertyName} bind in one direction, one-time, from the model to the binding

BINDING: ${attribute ==> propertyName} bind in one direction, from the element to the model

BINDING: ${attribute <=> propertyName} bi-directional, or two-way, between the element and the model

Let's look at some examples of this:

const model = {
  color: "red",
};

const template = `
<div>
    <input type="radio" \${'red' ==> color}>Red</input>
    <input type="radio" \${'green' ==> color}>Green</input>
</div>
`;

In this example you are binding a custom attribute on each element 'red' and 'green' to the color property in the model. When the radio button in this group is selected, it changes the data in the model property 'color'.

Another simple example:

const model = {
  userName: "",
};

const template = `
<div>
    <label>Enter Username: </label>
    <input type="text" \${value ==> userName}></input>
</div>
`;

This is a one way binding from the text field, that sets the data model value of userName to whatever is entered into the input field.

Let's look at a bidirectional example:

const model = {
  userName: "Bob",
};

const template = `
<div>
    <input type="text" \${value <=> userName}>\${userName}</input>
</div>
`;

The magic that exists here is that you can set username in the data model programmatically, and it will automatically change the rendered text in the input field. Or, you can type into the input field and it will dynamically change the value in the data model.

Bindings for events

So what if want to render a drop down select input, or a button? Peasy-UI gives you access to mapping the event listeners automatically and tying them into the data model.

BINDING: ${ event @=> callbackName}

Buttons provide easy examples for this, but all DOM events can be used.

const model = {
  clickHandler: (event: HTMLEvent, model: any, element: HTMLElement, eventType: string, object: any) => {
    window.alert("I got clicked");
  },
};

const template = `
<div>
    <button \${click @=> clickHandler}> Click Me! </button>
</div>
`;

Okay, there is a bit to unpack here. First lets focus on the binding, you can bind any HTML DOM event, such as change, input, click, mouseenter, etc... as an event binding, and then you provide the 'handler' callback which exists IN the data model.

Peasy passes 5 standard parameters into the handler for your convenience. The first parameter is the HTMLEvent that actually is fired.The second parameter is the 'localized' data model that is bound to the element. This CAN be tricky, because depending on your nesting of elements, it maybe be a localized data model for just that element, or if it is a top level binding, it will be the standard data model. We will get into nesting a bit later, but just know that another option is provided to help with this.

The third parameter is the target element that fired the event, so you can access any attributes nested in the element. The fourth element is the string representation of the event, such as 'click' or 'change' and this helps in case you bind multiple events to the same callback, you can distinguish which event triggered this callback. The final parameter is the overarching data model. Inside this object, regardless of how nested your binding is, will be an object that contains the model property, and you can navigate that object to have access to ANY property in the data model.

Binding whole elements to data model

Do you know how annoying it is to have to perform a documement.getElementById('myElement'); in your Javascript? Yeah, Peasy-UI makes that a bit easier.

BINDING: ${ ==> propertyName}

Let's look at this timesaver example:

const model = {
  myInputElement: undefined as HTMLElement | undefined,
};

const template = `
<div>
    <input type="text" \${==> myInputElement} />
</div>
`;

What this binding does is maps the DOM elements rendered and binds their reference inside the model. In this example, instead of having to do the getElementById() method, model.myInputElement is that reference after the first rendering cycle. The element has to render 'first' then the reference to it gets captured in the data model. This is why its set to undefined by default, then gets set to the element reference after the HTML gets injected into the DOM. So now to have access to the element value, i can just access model.myInputElement.value or any attribute in that element that I'd like access to.

Binding for rendering

What if you want to be selective about what gets rendered and maybe have portions of your template not rendered under certain conditions. Yup, Peasy-UI allows you to control overall rendering as well.

BINDING: ${=== propertyName}

BINDING: ${!== propertyName}

Let's looke at the example of this binding:

const model = {
  isDog: true,
};

const template = `
<div>
    <div \${=== isDog}> I am a Dog</div>
    <div \${!== isDog}> I am a Cat</div>
</div>

In this example you will only see one of the bound div's being rendered, and by toggling between true and false in the data model.isDog, you can control which div is being rendered.

Binding for arrays

Sometimes you need to list things out in the DOM. Examples may be forum posts, options in a select input, or list items in a nav bar. Peasy-UI gives you an iterable renderer, so you can translate a list or array in the data model to multiple element renderings.

BINDING: ${ item <=* propertyArray}

Let's give a simple example:

const model = {
  myItems: [{text: 'one', value: '1'},{text: 'one', value: '1'},{text: 'one', value: '1'}],
};

const template = `
<div>
    <select>
      <option \${opt <=* myItems} value="\${opt.value}">\${opt.text}</option>
    </select>
</div>

So this use case iterates over the 'myItems' property array in the data model, and renders a separate option element in the select tag.

Each rendered option tag has its own model scope as you can see, with opt.text and opt.value.

Bindings for components

So with larger projects, there is a desire to organize a code base and utilize code splitting to keep aspects of a project manageable. Peasy-UI allows for component based design. We will 'lightly' touch on this topic in this article as the overall component feature will get its own article for properly exploring its capabilities.

A component in Peasy-UI is any JavaScript object which contains a static, public template property and a static create method.

BINDING: ${ComponentName === state}

Let's look at one basic example, with more to follow in future article:

class MyComponent{
  public static template = `
  <div>
      <div> Hello \${name}</div>
      <div> My count is: \${count}</div>
  </div>
  `;

  constructor(public name: string,public count:number){}

  static create( state: {name:string, count:number}){
    return new MyComponent(state.name, state.count)
  }
}

const model = {
  MyComponent,
  componentData:{
    name: 'bob',
    count: 10,
  }
};

const template = `
<div>
    <\${MyComponent === componentData}>
</div>

So the MyComponent class must have a static create method that accepts incoming state, and a public static template. What Peasy-UI will do is set the local class properties as the internal state for each component, and will inject the class template into the overall project template.

This can let you break a larger project down into smaller pieces. There is a lot more you can do with components, and it warrants its own article to explore further.

Getters

The final binding idea to be covered is the usage of getters in the data model and what they bring to the table. Sometimes a simple primitive just doesn't cut it in the data model, and getters provide a means of providing more complicated logic and the return value will be the binding value to the binding. There's no unique binding tag to cover here, just an example:


const model = {
  val1: 1,
  val2: 3,
  get myGetter(){
      return this.val1 + this.val2;
  },
};

const template = `
<div>
    <span>My getter value is: \${myGetter}</span>
</div>

The nice part of using a getter is that it gets re-evaluated every rendering loop. So if any values change within its own logic, it will get updated.

More information

The author's twitter: Here

The author's itch: Here

Github Repo: Here

Discord Server: Here

Conclusion

So this article covered all the basics of the Peasy-UI library's data bindings, which is the magic that powers how the library is used to render essentially anything you need in the DOM. We discussed Text Bindings and Attribute Bindings. For each we covered the binding syntax, and how it can be used in examples.

In the next article we will dive deeper into events.

Introduction to Peasy-UI: Part 1 of the Peasy-UI Series

Justin Young — Sat, 20 Jul 2024 01:30:16 +0000

Table of Contents

What is Peasy-UI?
How does it work?
Demo Application
Usage
- Using node and a bundler
- CDN import
UIViews
- API
  - create
  - destroy
  - attached and detached
  - queue
Data Model
String Literal Template
Bindings
More information
Conclusion

What is Peasy-UI?

Peasy-UI (PUI or Peasy) is a small UI binding library. It started as a hobby project that grew some legs and became more than the author originally intended. Written by Jürgen Wenzel in early 2022, it started as a response to some game development community conversations around people attempting to make web based games using SPA frameworks. While SPA frameworks can be used to successfully make games on the web, most of them come with overhead and overkill for DOM reactivity from a game development and, more importantly, game loop perspective.

So the intent behind Peasy was to provide and ship the bare minimum amount of JavaScript necessary to allow for the library to control what was being rendered to the DOM, as well as being able to replace DOM content dynamically as a response to changes in the data model that the library owned and monitored. The design goals of Peasy-UI is to keep the package small (< 10kb), and should not require a build step to use.

Today, Peasy has grown its feature set to absorb controlling CSS and animations, binding DOM events, and allowing for component based design. I have even used Peasy to create Single Page Applications (SPA), which included a router feature for controlling component content. I have also successfully used server side control of the Peasy client, and asynchronously controlled the client content. Peasy-UI has also birthed several companion libraries too, such as Peasy-engine, Peasy-lighting, Peasy-input, Peasy-audio, and others... I have leveraged all of these to make a game framework that is powered by Peasy: Squeleto

To sum up: Peasy is powerful enough for most features needed on the web, but intentionally isn't going to replace React, Svelte, or Vue any time soon. It is extremely lightweight, easy to use, and performant to meet most web challenges.

How does it work?

Peasy works by the principle of creating UIViews to be rendered inside of the DOM. These UIViews own a data model, and also is provided a string literal template that represents the HTML to be rendered and parsed by Peasy. The linkage between the template provided and the data model is through bindings. When parsed, these bindings are then monitored and controlled by the library, and the binding 'links' information in the data model of the UIView, to the portion of the HTML in the template. Here is a quick example of what this can look like.

const model = {
  name: "Moookie",
};
const template = `
<div> 
    Hello: \${name}, how are you this evening?
</div>
`;

// Load the Peasy UI
await UI.create(document.body, model, template).attached;

// ---> Renders Hello: Mookie, how are you this evening?

What this tells Peasy to do is to monitor the value model.name, and render its content where the binding is present in the template....

Peasy will inject inside the body tag for the page, a div element with the inner text set to "Hello: Mookie, how are you this evening?" If I change model.name to another string, the content in the DOM immediately get replaced by Peasy.

Demo Application

I created a simple SPA tutorial using Peasy-UI. The application covers every topic that I will discuss further in future articles in this series. These include: bindings, events, CSS properties, animations, and component based design.

Demo Application

Usage

Peasy can be pulled into a JavaScript or TypeScript product via npm, and used with your favorite bundling toolset. Or, if your not using a bundler like Vite or Webpack, you can use the CDN link and embed the library into your html file and use it directly.

Using node and a bundler

npm i @peasy-lib/peasy-ui

import { UI } from "@peasy-lib/peasy-ui";

CDN import

One of the biggest features of Peasy is that it doesn't require a build step. You can import Peasy directly into your index.html and use it.

<script type="module">
  import { UI } from "https://cdn.skypack.dev/@peasy-lib/peasy-ui";
  const template = '...';
  const model = { ... };
  UI.create(document.body, template, model);
</script>

There are 4 concepts we are going to discuss in this first article:

UIViews and API
Data Model
String Literal Template
Data Bindings

UIViews

The atomic unit of PUI is the UIView. The UIView is a class that encapsulates an independent template and data model that is to be monitored by the library. You can use multiple UIViews in your application if you need them to be independently operated.

UIViews when created are given a DOM element as a host to be injected inside of. So you can use Peasy to control the content of just one element or it can control the entire application.

API

We will cover the 'key' API calls to get started. There are more on the UI and UIView class, but these are the common items.

create

UI.create(parent: HTML Element|string, model: {}, template: string):UIView;

This is the starting point of using Peasy. Takes in the element or the css selector string of the target DOM element to create the UIView for, the model object, and the string template literal with the HTML to be parsed. This returns a UIView that you can save and use later.

destroy

[UIView].destroy():void;

Calling the destroy() method on an active UIView will remove it from the active list of views being monitored.

attached and detached

(lifecycle properties)

[UIView].attached :Promise<void>;
[UIView].detached :Promise<void>;

The attached property of the UIView is a Promise that resolves when the DOM has the UIVeiw successfully rendered after the create() method. As such, one very common pattern used is awaiting this property on the chained UIView returned by the create() method on the UI...

await UI.create(document.body, model, template).attached;

This allows for the program to wait the short cycle it takes to attach the rendered content to the DOM preventing any issues making changes to the model before the UI has rendered properly. The detached property works in the same way if you are tearing down a UIView and you would want to wait for the completion of the DOM update before moving on.

queue

Sometimes you might need to wait with an action until Peasy UI has finished its current update. Passing a function to UI.queue will make it run after the current update is completed and before the next update starts.

// the input element has two bindings, showInput binds the rendering of the element
// and the inputElement binding captures the actual DOM element reference
// the button element has a click event toggleInput bound to the listener
const template = `
    <input \${===showInput} \${|=>inputElement}\>
    <button \${ click @=> toggleInput }>Toggle input</button>
`;
const model = {
  showInput: false, //this boolean controls the rendering of the input
  inputElement: undefined as HTMLInputElement | undefined, // this is the reference to the actual element
  toggleInput(event: any, model: any) {
    model.showInput = !model.showInput;
    if (model.showInput) {
      UI.queue(() => model.inputElement.focus());
      // Since inputElement is not available until after finished update,
      //schedules the focus call on the next render cycle
    }
  },
};

Data Model

The data model is the object that the library monitors for changes in state. When a value changes it triggers an update to the rendered UIView in the DOM.

The data model can store primitive data structures as well as callbacks, and getters.

const model = {
    isVisible: true,                        // booleans
    myName: "Mookie",                       // strings
    numLimitOfCycles: 100,                  //numbers
    listOfColors: ["White", "Red", "Blue"], // arrays
    userDetails: {                          //nested objects
        userName: 'bob',
        id: 1,
    },

    buttonClickHandler: () => {             // callbacks for DOM events
        console.log('I am clicked');
    },

    get isCyclesOverLimit () => {             // getters that get evaluated each cycle
        return (model.numLimitOfCycles <= 1000);
    },
}

String Literal Template

The string literal provides the HTML patterns for the library to parse and render. Nested inside the template are all the bindings that get parsed and evaluated each render cycle. One important item to note is that there MUST be one overarching parent element to hold all the HTML content. This element can be of any type, div, span, or whatever you want, just needs to be singular. This example below also shows how CSS can be used in the string literal template and with values bound to the data model. Think about the power that unlocks!!!! We will discuss events and animations in a later article.

const template = `
<style>
    button{
        position: fixed;
        top: 10px;
        left: 10px;
        width: \${buttonWidth}px;
    }
</style>

<div>
    <div> Here is some text content with this value bound: \${boundcontent}</div>
    <button \${click@=>buttonHandler}> Click Me! </button>

    <input type="text" \${value<=>inputTextString} />

    <div \${===isModalVisible}>
        I'm not always visible!
    </div>
</div>
`;

Bindings

The power of Peasy rests in the good amount of available bindings that exist. We will go into a much deeper assessment of bindings in the next article, with examples on how each can be used.

Text Bindings

${prop}             Binding from model property to attribute or text
${|prop}            One-time binding from model property to attribute or text

${'value' = prop}   Binding that renders value if model property is truthy
${'value' ! prop}   Binding that renders value if model property is not truthy

${|'value' = prop}  One-time binding that renders value if model property is truthy
${|'value' ! prop}  One-time binding that renders value if model property is not truthy

Attribute Bindings

attr <== prop     From model property to element attribute
attr <=| prop     One-time from model property to element attribute
attr ==> prop     From element attribute to model property
attr <=> prop     Two-way between element attribute and model property

event @=> method  Event from element attribute to model method

'value' ==> prop  From element to model property, used to bind values of
                  radio buttons and select inputs to a model property

==> (elProp)(:viewProp)   One-time that stores the element and/or the view
                          in corresponding model property

=== prop    Renders the element if model property is not false and not nullish
!== prop    Renders the element if model property is false or nullish

alias <=* list(:key)  From model list property to view template alias
                      for each item in the list. If key is provided
                      property key will be used to decide item equality

comp(:prop) === (state) Renders component (property with type or instance)
                        with a template and passes state, if component type, to
                        component's create method. If property is specified,
                        the created view will be stored in the model property

More information

GitHub Repo: Here

Discord Server: Here

Conclusion

We covered a ton of content in this introductory article. We discussed the background of Peasy-UI, and why it was created. We covered how to import Peasy into your project including via npm, or directly into your HTML by using a CDN.

We reviewed the key elements of the API of Peasy that you will regularly use. Then we went through the data model object, the string literal template, and finally we just started getting into the different bindings that are available in Peasy.

Over the course of the next few articles, we are going to dive deeper into:

binding walkthrough to explain each binding and show examples
binding events, like 'click' or 'change'
CSS pseudoclass helpers that exist with Peasy
animations
component design
using Peasy with Excalibur.JS game engine for UI layer and HUD elements

These articles have a companion demo app project tied to them that will be hosted on itch, and these will be visual references so one can see real-time application of the concepts we discuss in the articles.

We will close out this series with an overview of a simple SPA project to demonstrate how flexible and powerful Peasy can be.

How to use an auto-tiling technique in your next game project

Justin Young — Wed, 03 Jul 2024 01:15:10 +0000

As a game developer, if the thought of hand crafting a level does not appeal to you, then you may consider looking into procedural generation for your next project. Even using procedural generation, however, you still need to be able to turn your generated map arrays into a tilemap with clean, contiguous walls, and sprites that match up cleanly, as if it was drawn by hand. This is where a technique called auto-tiling can come into play to help determine which tiles should be drawn in which locations on your tilemap.

In this article, I will explain the concept of auto-tiling, Wang Tiles, binary and bitmasks, and then walk through the process and algorithms associated with using this tool in a project.

What is auto-tiling

Auto-tiling converts a matrix or array of information about a map and assigns the corresponding tile texture to each tile in a manner that makes sense visually for the tilemap level. This uses a tile's position, relative to its neighbor tiles to determine which tile sprite should be used. Today we will focus on bitmask encoding neighbor data, although there are other techniques that can be used to accomplish this.

One can get exposed to auto-tiling in different implementations. If you're using a game engine like Unity or Godot, there are features automatically built into those packages to enabling auto-tiling as you draw and create your levels. Also, there are software tools like Tiled, LDTK, and Sprite Fusion, that are a little more tilemap specific and give you native tools for auto-tiling.

Auto-tiling has provided the most benefit when we think about how we can pivot from tilemap matrices or flat indexes representing the state of a tilemap, to a rendered map on the screen. Let us say you have a tilemap in the form of a 2d matrix with 1's and 0's in it representing the 'walkable' state of a tile. Let us assign a tile as a floor (0) piece or a wall (1) piece. Now, one can simply use two different tiles, for example:

a grass tile
and a dirt path tile

We could take a tilemap matrix like this:

and use these two tiles to assign the grass to the 1's and the 0's to the path tile. It would look like this:

This is technically a tile-map which has been auto-tiled, but we can do a little better.

What are Wang tiles?

Wang tiles do not belong or associate with game development or tile-sets specifically, but come from mathematics. So, why are we talking about them? The purpose of the Wang tiles within the scope of game development is to have a series of tile edges that create matching patterns to other tiles. We control which tiles are used by assigning a unique set of bitmasks to each tile that allows us reference them later.

Wang tiles themselves are a class of system which can be modeled visually by square tiles with a color on each side. The tiles can be copied and arranged side by side with matching edges to form a pattern. Wang tile-sets or Wang 'Blob' tiles are named after Hao Wang, a mathematician in the 1960's who theorized that a finite set of tiles, whose sides matched up with other tiles, would ultimately form a repeating or periodic pattern. This was later to be proven false by one of his students. This is a massive oversimplification of Wang's work, for more information on the backstory of Wang tiles you can be read here: Wang Tiles.

This concept of matching tile edges to a pattern can be used for a game's tilemap. One way we can implement Wang tiles in game development is to create levels from the tiles. We start with a tile-set that represents all the possible edge outcomes for any tile.

These tile assets can be found here: Wang Tile Set

The numbers on each tile represents the bitmask value for that particular permutation of tile design. We then can see how you can swap these tiles for a separate texture below. In the image above, there are a couple duplicate tile configurations, and they are shown in white font.

The magic of Wang tiles is that it can be extended out and create unique patterns that visually work. For example:

As you can see from the tiles, every permutation of tile design is considered based on what potential neighbors each tile would have to marry up to.

What is a bitmask?

A bitmask is a binary representation of some pattern. In the scope of this conversation, we will use a bitmask to represent the 8 neighbors tiles of an given tile on a tilemap.

Quick crash course on Binary

So our normal counting format is designed as base-10. This means that each digit in our number system represents digits 0-9 (10 digits), and the value of each place value increases in power of base 10.

So in the number '42', the 2 represents - (2 * 10⁰) which is added to the 4 in the 'tens' place, which is (4 * 10¹), which equals 42.

(2 * 1) + (4 * 10) = 42

This in binary looks different, as binary is base-2, which means that each digit position has digits 0 and 1, (2 digits). This is the counting system and 'language' of computers and processors.

Quickly, let's re-assess the previous example of '42'. 42 in binary is 101010. Let's break this down in similar fashion.

Starting from the right placeholder and working our way left... The 0 in the right most digit represents 0 * 2⁰. The next digit represents 1 * 2¹... and on for each digit and the exponent increases each placeholder.

   0         1         0         1         0          1
_________________________________________________________________
(0 * 1) + (1 * 2) + (0 * 4) + (1 * 8) + (0 * 16) + (1 * 32) = 42

2 + 8 + 32 = 42

Bits, Bytes, and Bitmasks

That is how information in computers is encoded. We can use this 'encoding' scheme to easily represent binary information, like 'on' or 'off', or in this discussion, walkable tile or not walkable. This is why in the tile-set matrix example above, we can flag non-walkable tiles as '1', and walkable tiles as '0'. This is now binary encoded.

A bit is one of these placeholders, or one digit. 8 of this bits together is a byte. Computers and processors, at a minimum, read at least a byte at a time.

We can use this binary encoding for the auto-tiling by representing the state of each of a tile's neighbors into 8 bits, one for each neighbor. This means that the condition and status of each neighbor for a tile can be encoded into one byte of data (8 bits) and CAN be represented with a decimal value, see my earlier explanation about how the number 42 is represented in binary.

So the whole point of this section is to get to this example: we are going to encode the neighbor's data for an example tile.

Quick Demonstration

Now the tile we are assigning the bitmask to is the green, center tile. This tile has 8 neighbors. If I start reading the 1's and 0's from the top left and reading right, then down, I can get the value: 101 (top row) - 01 (middle row) - 101 (bottom row). Remember to skip the green tile.

All together, this is 10101101, which can be stored as a binary value, which can be converted to a decimal value: 173. Remember to start at the rightmost bit when converting.

   1         0         1         1         0          1          0          1
__________________________________________________________________________________
(1 * 1) + (0 * 2) + (1 * 4) + (1 * 8) + (0 * 16) + (1 * 32) + (0 * 64) + (1 * 128)

1 + 4 + 8 + 32 + 128 = 173

Now we can use that decimal value of 173 to represent the neighbor pattern for that tile. Every tile in a tilemap, can be encoded with their 'neighbors' bitmasks.

As you saw earlier, the wang tiles had bitmask values assigned to them. This is how we know which tile to substitute for each bitmask.

The Process

We have already covered the hard part. In this section we are pulling it all together in a walkthrough of the overall high level process.

Here are the steps we are covering:

Find or create a tile-set spritesheet that you would like to use
Create your tilemap data, however you like.
Loop through each index of tile, and evaluate the neighbor tiles, and assign bitmask
Map the bitmap values to the 'appropriate' tile in your tile-set (this is the long/boring part IMO)
Iterate over each tile and assign the correct image that matches the bitmask value
Draw your tilemap in your game

Creating a tile-set

Here is an example of a tile-set that I drew for the demo project.

These 47 tiles represent all the different 'wall' formations that would be required. I kept my floor tiles separate in a different file so that it is easier to swap out. The floor is drawn as a separate tile underneath the wall. Each tile represented in the grid is designed to match up with a specific group of neighbor patterns. Let's take the top-left tile:

This tile is intended to be mapped to a tile where there are walled neighbors on the right, below, and bottom right of the tile in question. There maybe a few neighbor combinations ultimately that may be mapped to this tile, in my project I found 7 combinations that this tile configuration would be mapped to.

If you look through each tile you can see how it 'matches' up with another mating tile or tiles in the map. For my implementation, I spent time testing out each configuration visually to see which tile different bitmasks needed to be mapped to.

Create your tilemap data

Now we will use either a 2d matrix or a flat array in your codebase, with each index representing a tile. I use a flat array, with a tilemap width and height parameter. It is simply preference.

You can manually set these values in your array, or you can use a procedural generation algorithm to determine what your wall and floor tiles. I can recommend my Cellular Automata article that I wrote earlier if you are interested in generating the tilemap procedurally. When this is completed, you'll have a data set that will look something like this.

Loop through tilemap and assign bitmasks

For each index of your array, you will need to capture all the states of the neighbor tiles for each tile, and record that value on each tile. I would refer to the previous section regarding how to calculate the bitmasks.

    // This loops through each tile in the tilemap
    private createTileMapBitmasks(map: TileMap): number[] {
        // create the array of bitmasks, the indexes of this array will match up to the index
        // of the tilemap
        let bitmask: number[] = new Array(map.columns * map.rows).fill(0);
        let tileIndex = 0;

        // for each tile in the map, add the bitmask to the array
        for (let tile of map.tiles) {
            bitmask[tileIndex] = this._getBitmask(map, tileIndex, 1);
            tileIndex++;
        }

        return bitmask;
  }

  // setting up neighbor offsets indexes /
    const neighborOffsets = [
        [1, 1],
        [0, 1],
        [-1, 1],
        [1, 0],
        [-1, 0],
        [1, -1],
        [0, -1],
        [-1, -1],
    ];

  // iterate through each neighbor tile and get the bitmask based on if the tile is solid
    private _getBitmask(map: TileMap, index: number, outofbound: number): number {
        let bitmask = 0;

        // find the coordinates of current tile
        const width = map.columns;
        const height = map.rows;
        let y = Math.floor(index / width);
        let x = index % width;

        // loop through each neighbor offset, and 'collect' their state
        for (let i = 0; i < neighborOffsets.length; i++) {
            const [dx, dy] = neighborOffsets[i];
            const nx = x + dx;
            const ny = y + dy;
            //convert back to index
            const altIndex = nx + ny * width;

            // check if the neighbor tile is out of bounds, else if tile is a wall ('solid') shift in the bitmask
            if (ny < 0 || ny >= height || nx < 0 || nx >= width) bitmask |= outofbound << i;
            else if (map.tiles[altIndex].data.get("solid") === true) bitmask |= 1 << i;
        }

        return bitmask;
    }

Map bitmask values to each tile sprite in spritesheet

Here is the monotonous part. For a byte, or an 8-bit word, the amount of permutations of tile patterns is 256. That's a lot of mappings. Now I did mine the hard way, manually, one by one. But there may be easier ways to do this. I use Typescript, so I will share a bit of what my mappings look like. Each number key in the object is the bitmask value, and its mapped to a coordinate array [x, y] for my spritesheet that I shared earlier in the article. Now, I could have put them in order, but that does not really serve any benefit.

export const tilebitmask: Record<number, Array<number>> = {
  0: [3, 3],
  1: [3, 3],
  4: [3, 3],
  128: [3, 3],
  32: [3, 3],
  11: [0, 0],
  175: [0, 0],
  15: [0, 0],
  47: [0, 0],
  207: [0, 5],
  203: [0, 5],
  124: [3, 5],
  43: [0, 0],
  ...

Iterate over the tiles and assign tile sprite

The last two steps we'll do together. Now we simply need to iterate over our tilemap, assign the appropriate sprite tiles. I'm using Excalibur.js for my game engine, and the code is in Typescript, but you can use whichever tool you would prefer.

draw(): TileMap {
    // call the method that loops through and configures all the bitmasks
    let bitmask = this.createTileMapBitmasks(this.map);
    let tileindex = 0;

    for (const tile of this.map.tiles) {
      tile.clearGraphics();

      // if the tile is solid, draw the base tile first, THEN the foreground tile
      if (tile.data.get("solid") === true) {
        // add floor tile
        tile.addGraphic(this.baseTile);

        // using the tile's index grab the bitmask value
        let thisTileBitmask = bitmask[tileindex];

        // this is the magic... grab the coordinates of the tile sprite from tilebitmask, and provide that to Excalibur
        let sprite: Sprite;
        sprite = this.spriteSheet.getSprite(tilebitmask[thisTileBitmask][0], tilebitmask[thisTileBitmask][1]);

        //add the wall sprite to the tile
        tile.addGraphic(sprite);

      } else {
        // if the tile is not solid, just draw the base tile
        tile.addGraphic(this.baseTile);
      }
      tileindex++;
    }
    return this.map;
  }

Demo Application

Link to Demo

Link to Repo

In this demo application, I'm using Excalibur.js engine to show how auto-tiling can work, and its benefits in game development. The user can click on the tilemap to draw walkable paths onto the canvas. As the walkable paths are drawn, the auto-tiling algorithm will automatically place the correct tile in its position based on the neighbor tile's walkable status.

There are some controls at the top of this app, a button to reset the tilemap settings back to not walkable, so one can start over. Also, two drop downs that let the user swap out tile-sets for different styles. This shows the benefits of having standardized Wang tiles for your tile-sets. For example, in this demo, we have three Wang tile-sets. When you swap them out, it can automatically draw them correctly into your tilemap.

Grass

Snow

and Rock

Why Excalibur

Small Plug...

Conclusions

That was quite a bit, no? We covered the concept of auto-tiling as a tool you can use in game development. We discussed the benefits of Wang tiles for your projects and how they allow for the auto selection of the correct tile sprites to use based off of bitmask assignments. We dug into bitmask and base-2 binary encoding to show how we were encoding the neighbor tile information into a decimal value so we could map the tile sprites appropriately. We finished this portion by doing an example tile encoding of neighbors to demonstrate the process.

We went through he process of auto-tiling, looking at tile-sets, looking at code snippets, and finishing at the demo application on itch. I hope you enjoyed this take on auto-tiling, as mentioned above, this is NOT the only way to do this, there are other ways of accomplishing the same effect. You also can tweak this to your own liking, for instance, you can introduce varying tiles so you can use different floor tiles, or adding decor on to walls to add additional variety and add a feeling of greater immersion into the worlds your building. Have fun!

Cellular Automata

Justin Young — Thu, 20 Jun 2024 21:01:53 +0000

I love procedural generation. As a hobbyist game developer, it is the concept and technique that I keep reaching for in my games. This article is about Cellular Automata, which follows suit of my previous articles regarding other procedural generation strategies for game development. In my last article, we studied the Wave Function Collapse Algorithm. Staying within that topical thread of procedural algorithms which can be leveraged in game development, let's turn our focus to Cellular Automata.

What is Cellular Automata

Cellular Automata, or CA for short, is an algorithm which has some key potential benefits within the field of game development. You may have seen in certain games, for example Dwarf Fortress or Terraria for example, where organic looking caves are generated, or some map patterns that look naturally grown. Essentially, it uses a grid based data set, and for each discrete unit in that grid, uses the state of all its neighbors to determine the end state of that cell in the ending simulation result.

History of Cellular Automata

Background

The early beginnings of the algorithm originated in the 1940's while scientists were studying crystal growth. That study, plus others including self-replicating robot experiments led to the realization of using a method of treating a system as a collection of discrete units (cells), and calculating their behavior based on the influence of each cell's neighbors. For more details on this: Cellular Automata

The Game of Life

In the 1970's, James Conway famously created a simulation called the Game of Life. This very simple simulation, which had only four rules, created a very dynamic and varied group of results that bounced between appearing random and controlled order. The rules determined each cell's future state as classified as dying due to underpopulation or overpopulation, creating a new living unit due to reproduction, or just continuing to exist with the correct balance of population around that unit.

Uses in Game Development

There are some common implementations of using Cellular Automata in game development. The classic trope is using the CA algorithm for generating tilemaps of organic looking areas or cave systems.

Another application is simulating the spread of fire across an area. Brogue is a good example of how this can be used.

Other aspects is simulating gas expansion in an area, or the spread of a virus, or enemy reproduction simulations for generating new enemies.

The Algorithm

For explaining the CA algorithm, we will demonstrate code snippets that demonstrate TypeScript and using Excalibur.js, but this can be done in any languages and framework of your choice.

Initialization

We start with a grid of tiles that are randomly filled with ones and zeroes.

const tiles:number[]=new Array(49);

// define the blue and white tiles for the TileMap
export const blueTile = new Rectangle({ width: 16, height: 16, color: Color.fromRGB(0, 0, 255, 1) });
export const whiteTile = new Rectangle({ width: 16, height: 16, color: Color.fromRGB(255, 255, 255, 1) });

//Utilizing PerlinNoise plug-in for Excalibur
generator = new PerlinGenerator({
    seed: Date.now(), // random seed
    octaves: 2, 
    frequency: 24, 
    amplitude: 0.91, 
    persistance: 0.95, 
  });

// This uses the TileMap object from Excalibur
export const tmap = new TileMap({
  tileWidth: 16,
  tileHeight: 16,
  columns: 7,
  rows: 7,
});

// Using the Perlin Noise Field, fill the Tilemap and tiles array with data
let tileIndex = 0;
for (const tile of tmap.tiles) {
  const noise = generator.noise(tile.x / tmap.columns, tile.y / tmap.rows);
  if (noise > 0.5) {
    tiles[tileIndex] = 1;
    tile.addGraphic(blueTile);
  } else {
    tiles[tileIndex] = 0;
    tile.addGraphic(whiteTile);
  }
  tileIndex++;
}

The algorithm will have us walk through the grid tile by tile and we will either leave the one or zero in place, or we will flip that value to the opposite, meaning a zero will become a one, and vice versa. The results of this assessment needs to be kept in a new or cloned array, as to not overwrite the starting array's values as you iterate over the tiles.

The Rules

The rules around flipping the values in each cell will depend on each implementation of the CA algorithm. These can be variable rules, each implementation can be unique in that instance. This gives you some agency and control over how you want your simulation to run. I've tailored this function with the flexibility to pass in the rules on each iteration. The rules are regarding how to handle out of bounds indexes, and what cutoff points are being used.


// Defining our CA function, passing in the grid, dimensions, and rules for OOB indexes and cutoff points
export function applyCellularAutomataRules(
  map: number[],
  width: number,
  height: number,
  oob: string | undefined,
  cutoff0: number | undefined,
  cutoff1: number | undefined
): number[] {
  const newMap = new Array(width * height).fill(0);

  let zeroLimit = 4;
  if (cutoff0) zeroLimit = cutoff0 + 1; //this creates the less than effect
  let oneLimit = 5;
  if (cutoff1) oneLimit = cutoff1;  // this creates the greater than or equalto

  for (let i = 0; i < height * width; i++) {
    for (let x = 0; x < width; x++) {
      const wallCount = countAdjacentWalls(map, width, height, i, oob); //counts walls in neighbors
      if (map[i] === 1) {
        if (wallCount < zeroLimit) {
          newMap[i] = 0; // Change to floor if there are less than cuttoff0 adjacent walls
        } else {
          newMap[i] = 1; // Remain wall
        }
      } else {
        if (wallCount >= oneLimit) {
          newMap[i] = 1; // Change to wall if there are cutoff1 or more adjacent walls
        } else {
          newMap[i] = 0; // Remain floor
        }
      }
    }
  }
  return newMap;
}

To note, this approach to the CA algorithm is for the sake of THIS article. Other approaches can be implemented. Let's define our rules for the scope of this article.

If the starting value for a tile is a zero, then to flip it to a one, the neighbors must have five or more ones surrounding the starting tile.
If the starting value for a tile is a one, then to flip it to a zero, the neighbors must have three or fewer ones surrounding the starting tile.
For tiles on the edges of the grid, which will not have 8 neighbors, out of bound regions will be treated as ones or 'walls'

tiles = applyCellularAutomataRules(tiles, 7, 7, 'walls', 3, 5);

With these rules in place, which can be modified and tailored to your liking, we can use them to determine the next iteration of the grid by going tile by tile and setting the new grid's values based on each tile's neighbors.

Counting Walls

For the rule on out of bound neighbors, you can use a variety of different rules to your liking. You can treat them as constants, like in this instance, we treat them as walls. You can have them be treated as floors, which will change how your simulation runs, producing a more 'open' result. You can also have the out of bound tiles mirror the value of the starting value, i.e. if your starting tile on the edge is a one, then out of bound tiles are all ones, and vice versa.

// This function takes in the grid and dims, which index is being inspected, and the rules on OOB tiles
function countAdjacentWalls(map: number[], width: number, height: number, index: number, oob: string | undefined): number {
  let count = 0;

  const y = Math.floor(index / width);
  const x = index % width;

  for (let i = -1; i <= 1; i++) {
    for (let j = -1; j <= 1; j++) {
      if (i === 0 && j === 0) continue;

      const newY = y + i;
      const newX = x + j;

      if (newY >= 0 && newY < height && newX >= 0 && newX < width) {
        const adjacentIndex = newY * width + newX;
        if (map[adjacentIndex] === 1) count++;
      } else {
        switch (oob) {
          // The 4 types of rules provided are for constant values, floor and wall, random
          // , and mirror
          case "floor":
            break;
          case "wall":
            count++;
            break;
          case "random":
            let coinflip = Math.random();
            if (coinflip > 0.5) count++;
            break;
          case "mirror":
            if (map[index]==1) count++;
            break;
          default:
            count++; // Perceive out of bounds as wall
            break;
        }
      }
    }
  }
  return count;
}

So starting at the first tile of the grid, you will look at the eight neighbors of the tile, in this instance, five of them are out of bound indexes. You add all the walls up in the neighbors, since the starting value is a zero, if the value is greater or equal to five, in the new grid/array, you will place a one in index zero for the new grid. This is how you flip the values. If, for instance, there would be less than five walls for the neighbors of this index, the value would have remained zero. You repeat this process for each tile in the grid/array.

Redraw your tiles

At the end, when you have completely iterated over each tile, you will have a new grid of tiles that are now set to zeroes or ones, based on that starting array. You can use this new grid as a completed result, or you can re-run the same simulation using this new grid as your 'new' starting array of data.

// function that clears out the existing tilemap and redraws it based on the new returned tile array
function redrawTilemap(map: number[], tilemap: TileMap, game: Engine) {
  game.remove(game.currentScene.tileMaps[0]);
  let tileIndex = 0;
  for (const tile of tilemap.tiles) {
    const value = map[tileIndex];
    if (value == 1) {
      tile.addGraphic(blueTile);
    } else {
      tile.addGraphic(whiteTile);
    }
    tileIndex++;
  }
  game.add(tilemap);
}

Walkthrough of the Algorithm

This walkthrough will simply use an array of numbers. With this array of numbers we will use a noise field, to represent random starting values, and then we will utilize the CA algorithm over multiple steps to highlight how it can be utilized.

Starting Point

Let's start with an empty array of numbers. We will represent the flat array as a two dimensional grid, with x and y coordinates. This is a 7 x 7 grid, which will be an array of forty-nine cells. As we process through the CA algorithm, we will be recording our results into a new array, as to not overwrite the input array while we are iterating over the indexes.

For the CA algorithm, it is suggested to fill the initial array with random ones and zeroes. You can use a [Perlin noise] https://en.wikipedia.org/wiki/Perlin_noise) field, or a Simplex noise field or just use your languages built in random function to fill the field. Here is ours:

Now we start the process of looping through each index and either leave them alone of flip the value between 0 and 1 based on the values of the neighbors. For this simulation we treat out of bound indexes as walls.

The first index

The first index of the array is the top left corner of the grid. This is relatively unique in the sense that this index only has three real neighbors. But as we mentioned before, out of bound (OOB) indexes will be treated as walls. If we count up each neighbor index, plus the OOB indexes, we get a value of seven. Since this count is higher than four, we will flip this indexes value to one in the new array we are creating.

Iterating

The second index of the array is a one. Now this index only has three OOB indexes that will count as walls.

This index only has one addition one in its neighbors, and if that's added to the three OOB index values, that puts our value to four. In our algorithm we are using today, the value that is required to change a one to a zero is if it has less than four walls as neighbors. With that, we will leave this one in place and insert this value in the new array.

We will follow this process for each index with the given rules below:

If the original value is one in the starting index, to be set to zero in the new array, the neighbor values have to be less than four.
If the original value is zero in the starting index, to be set to one in the new array, the neighbor values need to be five or higher.

Let's speed this process along a bit.

Finishing the first row.

Generating the 2nd row.

Generating the 3rd row.

Generating the 4th row.

Generating the 5th row.

Generating the 6th row.

Generating the Final row.

Now we have a completed array of new values. The thing about the CA algorithm that is favorable is that you can reuse the algorithm again on the new set of values to generate deeper levels of generation on the initial data set.

Let's run the simulation on this new data and see how it turns out.

So you see how numbers start to collect together to create natural, organic looking regions of walls and floors. This is particularly handy technique for generating cave shapes for tilemaps.

Demo Application

Link to Demo

Link to Repo

The demo simply consists of a 36x36 tilemap of blue and white tiles. Blue tiles represent the walls, and white tiles represent the floor tiles. There are two buttons, one that resets the simulation, and the other button triggers the CA algorithm and uses the tilemap to demonstrate the results.

Also added to the demo is access to some of the variables that manipulate the simulation. We can now modify the behavior of the OOB indexes. For instance, instead of the default 'walls', you can now change the sim to use random setting, mirror the edge tile, or set it constant to 'wall' or 'floor'.

You also have to ability to see what happens when you unbalance the trigger points. Above we defined 3 and 5 as the trigger points for flipping a tile's state. You have the ability to modify that and see the results it has on the simulation.

The demo starts with a noise field which is a plugin for Excalibur. Using a numbered array representing the 36x36 tilemap, which has ones and zeroes we can feed this array into the CA function. You can repeatedly press the 'CA Generation Step' button and the same array can be re-fed into the algorithm to see the step by step iteration, and then can be reset to a new noise field again to start over.

Why Excalibur

Small Plug...

Conclusions

So, what did we cover? We discussed the history of Cellular Automata and some generalized use cases for CA within the context of game development. We covered the implementation of the steps to take to perform the simulation on a grid of data, and then we conducted a walk through example of using the algorithm. Finally, we introduced a demo application hosted on itch, and shared the repository in case one is interested in the implementation of it.

This algorithm is one of the easier to implement, as the steps are not that complicated either in cognitive depth or in mathematical processing. It is one of my favorite simple tools that reach for especially for tilemap generation when I create levels. I urge you to give it a try and see what you can generate for yourself!

Wave Function Collapse

Justin Young — Sun, 02 Jun 2024 17:45:00 +0000

One challenge of indie game development is about striking a balance. Specifically, the balance between hand crafted level design, player replay-ability, and the lack of enough hours in a day to commit to being brilliant at both. This is where people turn to procedural generation as a tool to help strike that balance. One of the most magical and interesting tools in the proc gen toolbox is Wave Function Collapse (WFC). In this article, we'll dive into the how/why of WFC, and how you can add this tool to your repertoire for game development.

What is Wave Function Collapse

WFC is a very popular procedural generation technique that can generate unique outputs of tilemaps or levels based off prompted input images or tiles. WFC is an implementation of the model synthesis algorithm. WFC was created by Maxim Gumin in 2016. The WFC algorithm is VERY similar to the model synthesis algorithm developed in 2007 by Paul Merrell. For more information on WFC specifically, you can review Maxim's Github repo here.

It is based off the theory from quantum mechanics. Its application in Game Development though is a bit simpler. Based on a set of input tiles or input image, the algorithm can collapse pieces of the output down based on the relationship of that tile or image area.

Example input image:

(Yes I do have an unhealthy fascination with the original Final Fantasy)

Example output images:

Entropy

Digging into the quantum mechanics context of WFC will introduce us to the term Entropy. Entropy is used as a term that describes the state of disorder. The way we will use it today is the number of different tile options a certain tile can be given the state of its neighbor tiles. We will demonstrate this further down.

The concept essentially states that the algorithm selects the region of the output image with the lowest possible options, collapses it down to its lowest state, then using that, propogating the rules to each of the neighbor tiles, thus limiting what they can be. The algorithm continues to iterate and collapsing down tiles until all tiles are selected. The rules are the meat and potatoes of the algorithm. When you setup the algorithm's run, you not only provide the tileset, but also the rules for what tiles can be.

For this discussion, as the demo application focuses on using WFC with the ExcaliburJS game engine, we are focusing on the simple tile-based WFC approach.

Walkthrough of the algorithm

The Rules

The rules are arguably the most critical aspect of the algorithm. For the simple tile-based mapping, this includes details and mappings between each tile and what other tiles can be used as neighbors. If you were doing the input image form of WFC, the input image's design would dictate the rules pixel by pixel.

Let us consider this subsection of the tilemap to demonstrate this:

Let's identify each tile as tree, treetop, water, road, and grass. For the sake of simplicity, we will focus on just four of them: tree,water, grass, and treetop.

We will define some rules for the tiles as such.

let treeTileRules = {
  up: [treeTopTile, grassTile, waterTile],
  down: [grassTile, waterTile, treeTile],
  left: [grassTile, waterTile, treeTile],
  right: [grassTile, waterTile, treeTile],
};

let grassTileRules = {
  up: [treeTile, grassTile, waterTile],
  down: [grassTile, waterTile, treeTile],
  left: [grassTile, waterTile, treeTile],
  right: [grassTile, waterTile, treeTile],
};

let treeTopTileRules = {
  up: [grassTile, waterTile, treeTopTile],
  down: [treeTile],
  left: [grassTile, waterTile, treeTile],
  right: [grassTile, waterTile, treeTile],
};

let waterTileRules = {
  up: [treeTile, grassTile, waterTile],
  down: [grassTile, waterTile, treeTile],
  left: [grassTile, waterTile, treeTile],
  right: [grassTile, waterTile, treeTile],
};

What these objects spell out is that for tiles above the tree tile, it can be a grass, water, or treetop tile. Tiles below the treetile can be another tree tile, or water, or grass... and so on. One special assignement to note, that below a treeTop tile, can ONLY be a treeTile.

We can proceed to follow this pattern for each of the tiles, outlining for each tile what the 4 neighbor tiles CAN be if selected.

The Process

The process purely starts out with an empty grid... or you actually can predetermine some portions of the grid for the algorithm to build around... but for this explanation, empty:

Given that none of the tiles have been selected yet, we can describe the entropy of each tile as essentially Infinite, or more accurate, N number of available tiles to choose from. i.e. , if there are 5 types of available tiles, then the highest entropy is 5, and each tile in this grid is assigned that entropy value.

If we entered the algorithm with predetermined tiles, or what we could call collapsed, then the entropy of the surrounding neighbors of those tiles would have a lower entropy as dictated by the rules we discussed above.

Let's begin by selecting a random tile on this grid... {x: 3,y: 4}. Due to the fact that all its neighbors are empty, it's pool of available tiles is 4, tree, grass, water, or tree top. Let us pick tree, as this can simply be randomly picked from the set.

This leads us into the idea of looping through all the tiles and setting their entropy value based on what their neighbors are... we have 4 available tiles for this experiment, so 4 will be the highest entropy value.

Take note that the neighbors of our fully collapsed tile are not at entropy 4, but at 3, as for each of these neighbors, our 'rules' for the tree tile reduces their possible options. So now we start the process again, but instead of randomly selecting any tile, we will form a list of the lowest entropy tiles, and that becomes our available pool. So, in this example:

[{x:3,y:3}, {x:2,y:4}, {x:4, y:4}, {x:3,y:5}] all have entropy values of 3, so they are what we select.

4,4 is selected from that pool, and based on the rules, it can be grass, water, or tree. Randomly selected: tree again. Looping through the tiles and resetting the entropy, we get a new pool of tiles.

4,3 is the next selected from the new pool of lowest entropy tiles, and it becomes a grass tile. Looping through the tiles and resetting entropy, we notice something different.

We see our first shift in the pool of lowest entropy. The reason behind tile 3,3 being entropy level 2 is due to the rules of grass and tree tiles.

let treeTileRules = {
  up: [treeTopTile, grassTile, waterTile],
  down: [grassTile, waterTile, treeTile],
  left: [grassTile, waterTile, treeTile],
  right: [grassTile, waterTile, treeTile],
};

let grassTileRules = {
  up: [treeTile, grassTile, waterTile],
  down: [grassTile, waterTile, treeTile],
  left: [grassTile, waterTile, treeTile],
  right: [grassTile, waterTile, treeTile],
};

The left field for grass tiles allows for grass, water, and tree... while the up field for tree only allows grass, water, and treetop. So between those two fields, there are only 2 tile types that match both requirements, thus there are only 2 available tiles to select and now and entropy of 2.

The next iteration of the algorithm has only one tile in its pool of lowest entropy, 3,3 so it gets collapsed to either water or grass based on its neighbors, so it becomes grass as a random selection.

This algorithm carries on until there are no more tiles to collapse

One note on this example is that we have really limited the amount of different tiles that are being accessed, and you see this manifest itself in the entropies of 3,4 consistently. The rules also are fairly permissive, which is why we don't see a huge variation of entropies. More tiles available, and more restrictive rules, will drive much more variation in the entropy scores that will be witnessed.

Collisions

What you will find with this algorithm that there maybe created a conflict where there is no available tiles to select based on the neighbors. This is called either a conflict or a collision, and can be handled in a couple different ways.

One thought is to reset the map and try again. From a process perspective, sometimes this is just the easiest/cheapest method to resolve the conflict.

Another approach is to use a form of the command design pattern, and saving a stack of state snapshots that are captured during each step of the algorithms iteration, and upon reaching a collision, 'backtrack' a bit and retry and generate again from a previous point. The command design pattern essentially unlocks the undo button for an algorithm, and allows for this.

Demo Application

Link To Repo

Link To Demo

The demo application that's online is a simple, quick simulation that runs a few algorithm iterations... and can regenerate the simulation on Spacebar or Mouse/Touch tap.

First, it uses WFC to generate the terrain, only using the three tiles of grass, tree, treetops.

Second, it finds spots to draw two buildings. The rules around this is to not collide the two buildings, and also not have the buildings overrun the edges of the map. I use WFC to generate random building patterns using a number of tiles.

Finally, and this has nothing to do with WFC, I use a pathfinding algorithm I wrote to find a path between the two doors of the houses,and draw a road between them... I did that for my own amusement.

Pressing the spacebar in the demo, or a mouse tap, attempts to regenerate another drawing. Now, not every generation is perfect, but this seems to have a >90% success rate, and for the purposes of this article, I can accept that. I intentionally did not put in a layer of complexity for managing collisions, as I wanted to demonstrate what CAN happen using this method, and how one needs to account for that in their output validation.

Why Excalibur

Small Plug...

Conclusions

Wrapping up, my goal was to help demystify the algorithm of Wave Function Collapse. There are some twists to the pattern, but overall it is not the most complicated of generation processes.

We also discussed the concept of Entropy, and how it applies to the algorithm overall, in essence it helps prioritize the next tile to be collapsed. Collapsing a tile is simply the process of picking from of available tiles that a specific tile CAN be by means of the rules provided.

In my experience, and I've done a few WFC projects, the rules provide the constraints of the algorithm. Ultimately, it is where I always spend the most time tweaking and adjusting the project. Too tight of rules, and you'll need to be VERY good at managing collisions. However, too few rules, and you're output maybe a very noisy mess.

I suggest you give WFC a try, it can be VERY fun and rewarding to see the unique solutions it can come up with.

Pathfinding Algorithms Part 2 with A*

Justin Young — Sun, 26 May 2024 02:15:00 +0000

This is a continuation of our discussion on pathfinding. In the first part of our discussion, we investigated Dijkstra's algorithm. This time, we are digging into A* pathfinding.

Link to Part 1

Link to Pathfinding Demo

Pathfinding, what is it

Quick research on pathfinding gives a plethora of resources discussing it. Pathfinding is calculating the shortest path through some 'network'. That network can be tiles on a game level, it could be roads across the country, it could be aisles and desks in an office, etc. etc.

Pathfinding is also an algorithm tool to calculate the shortest path through a graph network. A graph network is a series of nodes and edges to form a chart. For more information on this: click here.

For the sake of clarity, there are two algorithms we specifically dig into with this demonstration: Dijkstra's Algorithm and A*. We studied Dijkstra's Algorithm in Part 1.

A* Algorithm

A star is an algorithm for finding the shortest path through a graph that presents weighting (distances) between different nodes. The algorithm requires a starting node, and an ending node, and the algorithm uses a few metrics for each node to systematically find the shortest path. The properties of each node are fCost, gCost, and hCost. We will cover those in a bit.

Quick History

The A* algorithm was originated in its first state as a part of the Shakey project. That project was about designing a robot that could calculate its own path and own actions. In 1968, the first publishing of the A* project happened and it describes its initial heuristic function for calculating node costs.

A heuristic function is a logical means, not necessarily perfect means, of solving a problem in a pragmatic way.

Over the years the A* algorithm has been refined slightly to become more optimized.

Algorithm Walkthrough

Load the Graph

We first load our graph, understanding which nodes are clear to traverse, and which nodes are blocked. We also need to understand the starting node and ending node as well.

Cost the nodes

We first will assess the cost properties for each node. Cost is a term we are using that represents a distance between nodes. This will be a method that assigns the fCost, gCost, and hCost to each node.

Let's discuss these costs first. The costs are a weighting of each node with respect to its positioning between the starting and ending nodes.

The fCost of a tile is equal to the gCost plus the hCost. This is represented as such:

f=g+h

The gCost of the node is the distance cost between the current node and the starting node.

The hCost of the node is the 'theoretical' distance from the current node to the ending node. This is why we discussed heuristics earlier. This value is an estimate of the distance, a best guess. This makes guessing for a rectangular tilemap easy, since all tiles are distance 1 from each other in a grid, the method of guessing is just using the tile positions of the two nodes and using Pythagorean theorem to assess the distance. If the grid is irregular, some spatial data may need to be injected into the graphs creation to facilitate this heuristic, for example: x/y coordinate locations maybe.

Thus, the fCost is the sum of these two values. While simplistic, this is the value that is leveraged in the algorithm to determine the 'best' path.

Setup Buffers

After we've looped through all the nodes and costed them appropriately, we will utilize a buffer called openNodes. We will push the starting node into this, as it is the only node we 'know' about as of yet. We will use this openNodes buffer for much of the iterations we conduct in this algorithm.

We will leverage another buffer we will call either 'checked' or 'closed' buffer, and this is where the results of our algorithm will exist, as we process tiles from openNodes into this buffer.

Iteration

Then we get into the repeating part of the algorithm.

Look for the lowest F cost square in the open list. Make it the current square.
Move the current square to the closed buffer (list). Remove from openNodes, move to 'checked' nodes.
Check if the new current node is the endnode, this is the finishing condition. using the parent node properties of each node, walk backwards to the starting node, that's the shortest path
If not ending node, review all neighbor squares of current square, if a neighbor is not traversable, ignore it
Check each neighbor is in checked/closed list of nodes, if not, perform parent assignment, and add to open node list

This series continues to iterate while neighbors are being added to the open node list.

Example

Let's start with this example graph network.

We will manage our walkthrough with two different lists, open nodes and checked nodes. Black tiles above represent nodes that are not traversable. Let's define our start and stop nodes as indicated by the green S node and the blue E node.

The first step of A* algorithm is costing all the nodes, and let's see if we can show this easily.

For more clarity on the 'costing' step, let's talk through the core loop that is applied to each tile.

My process is to loop through each tile, and assuming it has either coordinates or and index, I can determine its distance from the start node and end node.

Let's do the first tile together. The first tile is coordinates (x:0, y:0), and the start node is coordinates (x: 1, y:1), while the end node is (x: 4,y:5). The gCost for this tile we can use Pythagorean theorem to calculate the distance as the hypotenuse.

gCost = Math.sqrt(Math.pow((1-0), 2) + Math.pow((1-0)), 2));

This gives us a gCost of ~1.41.

We can repeat this equation for the hCost, but it is with respect to the end node coordinates.

hCost = Math.sqrt(Math.pow((4-0), 2) + Math.pow((5-0)), 2));

This yields a hCost of ~6.40.

Knowing both now, we can determine the fCost of that node or tile, by adding the two together, making the fCost 7.82... with rounding.

We can repeat this process for each tile in the graph.

Why am I using floating point values here? There's a reason, if I simply use integers, then the distances wouldn't have enough resolution in digits, creating a little more unoptimized iterations, as the number of cells with equal f Costs would increase, here the fCosts are more absolute, and we will reduce the iterations. Simply put, if all the fCosts between 5.02 - 5.98 all are represented as 5 as an integer, it muddies up how the algorithm moves through and prioritizes the 'next' cell to visit. With floating points, this is explicit. Being a grid, all the distances are simple hypotenuse calculations using Pythagorean theorem.

Before we jump into the overall repetitive loop, we will add the startnode into our list of opennodes.

Now the algorithm can start to be repetitive. We set the startnode to the current node, and move it from open to checked lists.

We first check if our current node is the end node, which it is not, so we proceed.

The next step is to select the lowest fCost, and since the starting node is the only node in openlist, it gets selected, otherwise we would have selected randomly from the lowest value fCosts in the open node list. Now we look at all the neighbors. I will designate the pale yellow as our 'open node' list. We will use different colors for 'checked'.

None are in the checked list, so we add them all to the opennodes list, and assign the current node as each nodes parent. To note, if a node is not traversable (black) then it gets ignored at this point, and not added to the list.

This then repeats as long as nodes are in the open node list, if we run out of open nodes without hitting the end node, then there's no path. When we hit the end node, we start building our return list by looping back through the parent nodes of each node. Starting at the end node, it will have a parent, that parent will have a parent... and so on until you hit the start node.

Let's walk through the example. Let's pick a tile with lowest f cost. As we select new 'current' nodes, we move that node to our checked list so it no longer is in the open node pool.

The lowest cost is 5.02, and grab its neighbors. Along the way we are assigning parent nodes, and adding the new neighbors to the openNodes list.

...but we keep selecting lowest cost node ( f cost of 5.06 is now the lowest to this point), we add neighers to opennodes, assign them parent nodes...

.. the next iteration, the fCost of 5.24 is now lowest, so it gets 'checked', and we grab its neighbors, assign parents..

.. the next iteration, there are two nodes of 5.4 cost, so let's see how this CAN play out, and the algorithm starts to make sense at this point.

Let's pick the high road...

The new neighbors are assigned parents, and are added to the overall list of open nodes to assess. Which is the new lowest fCost now? 5.4 is still the lowest fCost.

Yes, the algorithm went back to the other path and found a better next 'current' node in the list of open nodes. The process is almost complete. The next lowest fCost is 5.47, and there is more than one node with that value, so for the sake of being a completionist...

Still the lowest fCost is 5.47, so we select the next node, grab neighbors, assign parents... one thing I did differently on this table is showing the fCost of the ending node, which up till now wasn't necessary, but showing it here lets one understand how the overall algorithm loops, because the end node HAS to be selected as the next lowest cost node, because the check for end node is at the beginning of the iteration, not in the neighbor evaluation. So in this next loop, I don't make it yellow, but the end node is now been placed AS A NEIGHBOR into the list of open nodes for evaluation.

We now have our path, because the next iteration, the first thing we'll do is pick the lowest node fCost (5.0) and make it the current tile, and then test if it is the end node, which is true now.

We can return its path walking back all the parent node properties and see how we got there along the way.

The test

Link to Demo

Link to Github Project

The demo is a simple example of using a Excalibur Tilemap and the pathfinding plugin. When the player clicks a tile that does NOT have a tree on it, the pathfinding algorithm selected is used to calculate the path. Displayed in the demo is the amount of tiles to traverse, and the overall duration of the process required to make the calculation.

Also included, are the ability to add diagonal traversals in the graph. Which simply modifies the graph created with extra edges added, please note, diagonal traversal is slightly more expensive than straight up/down, left/right traversal.

Why Excalibur

Small Plug...

You can also find it on GitHub.

Conclusion

For this article, we briefly reviewed the history of the A* algorithm, we walked throught the steps of the algorithm, and then applied it to an example graph network.

This algorithm I have found is faster than Dijkstra's Algorithm, but it can be tricky if you're not using a nice grid layout. The trick comes into the 'guessing' heuristic of the distance between the current node and the endnode (hCost). If you using a grid, you can use the coordinates of each node and calculate the hypotenuse as the hCost. If it is an unorganized, non standard shaped graph network, this becomes trickier. For the moment, for the library I created, I am limiting A* to grid based tilemaps to make this much simpler. If the grid is not simple, I use Dijkstra's algorithm.