In this final week's submission for Hashnode's #4articles4weeks Writeathon, I'm circling back to DCL, a custom javascript frontend develop-as-needed framework that I created while working on Projectree.

What Is DCL

DCL is short for Danidre's Client Library. I needed to spend July 2022 working on an open source project that uses PlanetScale, however, half of that time was spent working on the framework to use in the project.

DCL Features:

Since DCL was developed alongside Projectree, it is not a fully featured developer rich library. I started with rendering components and handling state with JavaScript, and expanded as I needed more features.

At the July 2022's release of Projectree, DCL supports:

• Nested components
• Routing
• Component props
• Component state
• Global context
• Component rerendering
• Input management*

Why I Created DCL

The last time I created a project with a frontend library (React; February 2020), I spent 2 months learning and applying what I learnt. Also, many build steps were involved, and tedious setup was required. For the hackathon, I only had 1 month. I wanted to work on an application with only HTML, CSS, and JavaScript. I also wanted full control of the application, instead of spending days trying to solve an error if I got stuck.

At the same time, I wanted to be able to reuse elements on a page instead of repeating code on multiple pages, and I wanted to be able to have values update without having to read and write from elements in JavaScript.

Instead of let age = document.getElementById("age").value and document.getElementById("age").value = newAge for getting and setting values, I just wanted to change a variable once, and its represented element should change automatically.

Benefits of DCL

As a result, using DCL has many perks:

• Easy setup
• Minimal JavaScript file
• No build time required
• Develop, drag and drop to deploy
• No complex language necessary
• No relearning architecture

How I Created DCL

Components

The main class in DCL is the DCL class. All other elements can extend this component class. This class handles nested components, unique component state, and more. Below is a simple overview of its functions:

class DCL {
    constructor(props = {}) {
        this.props = props;
        this.state = {};
        this._dclId = _generateUID();
        this._refs = {
            children: [],
            stateFuncIDs: [],
            createFuncIDs: [],
            contextFuncIDs: []
        };
    }

    setState(key, value) {}
    static stateStore = {}

    createFunc(func, ...args) {}
    static funcStore = {}

    onMount() {}
    onUnmount() {}

    _mount(parent) {}
    _unmount() {}

    render() {}
    _getHTML() {}
    _rerender() {}
    static _validateDCLX(dclx = "") {}

    monitorContext(key, callback, ...args) {}
    static getContext(key) {}
    static setContext(key, value) {}
    static clearContext(key)
}

window.DCL = DCL;

Creating a Basic Component

A simple component can be created using the following:

class Button extends DCL {
    constructor(props) {
        super(props);
    }

    render() {
        const onClick = this.props.onClick || "null";
        return `<button onclick="${onClick}">${this.props.name}</button>`;
    }
}

As possibly assumed, the render function describes how the component should look.

This Button component renders a button element, with a name passed as a property. When the component is first created, the onMount function is called. This is where developers can make requests to retrieve information from APIs or servers. However, since this Button component does not have a need for it, nothing will happen here.

Creating an Interactive Component

The following component will give a better example of the methods available for each component:

class Todo extends DCL {
    constructor(props) {
        super(props);
        this.state = {
            taskname: "",
        }
    }

    render() {
        const updateTaskname = this.setState("taskname", (oldTaskname, evt) => {
            return evt.target.value;
        });
        const displayTask = this.createFunc((evt) => {
            alert(this.state.taskname);
        });
        return `
            <h1>Task</h1>
            <input onblur="${updateTaskname}" value="${this.state.taskname}"/>
            ${new Button({name:"Alert Task", onClick: displayTask})._mount(this)}
        `
    }
}

Many things are going on here:

• The Todo component represents a task that the user can edit. When created, the task (stored as taskname) is empty.
• Then, we try to render 3 elements to represent this component: an h1 element representing the task label, an input element representing the task itself, and a Button component that can display the task's name to the user.

If we try to run this, however, we get the following error:

Validating Components

Following React's convention, each DCL component should only return one top level element. Instead, the elements should be wrapped into a div or other enclosing element:

return `
    <div>
        <h1>Task</h1>
        <input onblur="${updateTaskname}" value="${this.state.taskname}"/>
        ${new Button({name:"Alert Task", onClick: displayTask})._mount(this)}
    </div>
`

That is because DCL does not have a Virtual DOM that tracks changes in element states. Instead, the _getHTML method creates a temporary element that:

1. Wraps around each component's returned render html:

<dcl>
    <div>
        <h1>Task</h1>
        <input onblur="updateTaskName()" value=""/>
        <button onclick="displayTask()">Alert Task</button>
    </div>
</dcl>

1. Assigns a unique identifier to itself:

<dcl data-dcl-id="todo_l7xr2462wjgidez7kf">
    <div>
        <h1>Task</h1>
        <input onblur="updateTaskName()" value=""/>
        <button onclick="displayTask()">Alert Task</button>
    </div>
</dcl>

1. Passes it to the first child element:

<dcl data-dcl-id="todo_l7xr2462wjgidez7kf">
    <div data-dcl-id="todo_l7xr2462wjgidez7kf">
        <h1>Task</h1>
        <input onblur="updateTaskName()" value=""/>
        <button onclick="displayTask()">Alert Task</button>
    </div>
</dcl>

1. And removes itself:

<div data-dcl-id="todo_l7xr2462wjgidez7kf">
    <h1>Task</h1>
    <input onblur="updateTaskName()" value=""/>
    <button onclick="displayTask()">Alert Task</button>
</div>

That way, the intended html structure of the page is maintained, and DCL is able to recognize which elements need to change upon rerender.

DCL's _validateDCLX method is called internally to ensure that only one top level element is returned for each component.

In this case, DCLX stands for DCL XML, DCL's markup syntax.

Now, the task component renders correctly, and is functional:

As possible imagined, this.setState and this.createFunc methods allow functions to be called on each element. Similar to React, setState changes the component's state and rerenders it to reflect the change.

The Good

When setState is triggered, the component searches the DOM for the element with that unique id, removes it, and rerenders the component and its children.

The Bad

Since DCL uses no Virtual DOM, each component must keep track of their nested components (children). That is why the Button has the _mount(this) function. _mount accepts a parent component, and adds that child to the parent's list of components. That way, when a parent component has to be removed or rerendered, it can loop through its children and unmount them appropriately.

Although it works, the DCLX syntax for nested components is a bit...unappealing.

The Ugly

React and other frameworks have build steps that generate the appropriate JavaScript that allows functions and methods in each component to retain their proper scope. However, DCL does not have this, as each component returns the html as a string, which is then appended to the DOM using innerHTML. As a result, functions defined this way cannot be returned as a string and executed correctly.

To address that, the setState and createFunc methods actually store the passed functions in a global scope controlled by DCL (stateStore and funcStore), and returns the string name of the method, so it is included in the innerHTML and "works":

1. The developer defines the function:

const updateTaskname = this.setState("taskname", (oldTaskname, evt) => {
    return evt.target.value;
});

1. It is internall added to DCL's stateStore:

setState(key, value) {
    const funcID = `stateID_${this._dclId}_${_generateUID()}`;

    DCL.stateStore[funcID] = (evt) => {
        if(typeof value === "function") {
            const prevState = _deepClone(this.state);
            this.state[key] = value(prevState, evt);
        } else {
            this.state[key] = value;
        }

        this._rerender();
    }

    // ...other code
}

1. It is also added to the component's references list (so they can delete it when unmounting):

setState(key, value) {
    // ...other code

    this._refs.stateFuncIDs.push(funcID);
}

1. The string representation is finally returned:

setState(key, value) {
    // ...other code

    return `DCL.stateStore.${funcID}(event)`;
}

Thus, the innerHTML becomes the following:

<input onblur="DCL.stateStore.stateID_todo_l7xr2462wjgidez7kf_l7xr5olmp8tsb1cguf(event)" value=""/>

Whenever the input element is blurred, it will call the function since it can be found on the webpage.

The same process occurs with the createFunc method: it is added to DCL's funcStore, referenced by the component so it can be removed later, and returned as a string for the innerHTML.

This method is ugly because it pollutes the webpage's global scope. I do prevent memory leaks by deleting each method when its referenced component is unmounted, however.

Monitoring Global Changes

Internally, DCL uses a pub/sub method to broadcast changes. Each component can 'hook' onto changes using monitorContext. Then, whenever that property is changed, the 'hooked' component rerenders:

class Elem1 extends DCL {
    constructor(props) {
        super(props);
        this.num = DCL.getContext("number");
    }
    onMount() {
        this.monitorContext("number", (value) => {
            this.num = value;
        });
    }
    render() {
        return `
            <div>
                <h1>Elem 1</h1>
                <p>Num: ${this.num}</p>
            </div>
        `
    }
}

class Elem2 extends DCL {
    render() {
        const incrementNum = this.createFunc((evt) => {
            const prevNumber = DCL.getContext("number") || 0;
            DCL.setContext("number", prevNumber + 1);
        });

        return `
            <div>
                <h1>Elem 2</h1>
                ${new Button({name:"Increase Number", onClick: incrementNum})._mount(this)}
            </div>
        `
    }
}

class Main extends DCL {
    constructor(props) {
        super(props);

        DCL.setContext("number", 0);
    }
    render() {
        return `
            <div>
                ${new Elem1()._mount(this)}
                ${new Elem2()._mount(this)}
            </div>
        `
    }
}

Whenever the button from Elem2 is clicked, DCL's number property increases. Since Elem1 is 'hooked' to the number property (from monitorContext), a rerender is triggered each time the number property changes, so Elem1 successfully reflects the change each time.

Handling Page Routes

One of the intentions of my library was to treat pages as components and render a different component based on the url navigated to. For that, I needed DCL to handle routes as well. Thus, I created a Router component that solves this:

class Router extends DCL {
    constructor(props) {
        super(props);

        this.routes = props.routes || [];
        this.defaultRoute = props.defaultRoute || routes[0];
        this.view = null;
    }
    onMount() {
        // redetermine route when the back button is triggered
        window.addEventListener("popstate", this.determineRoute);

        // navigate to new link without refreshing page if specific element is clicked
        document.body.addEventListener("click", (evt) => {
            if(evt.target.matches("[data-dcl-link]")) {
                evt.preventDefault();
                history.pushState(null, null, evt.target.href);
                this.determineRoute();
            }
        });

        this.determineRoute();
    }

    determineRoute() {
        const routes = this.routes;

        // test each route for potential match
        const potentialMatches = routes.map(route => ({
            route: route,
            result: location.pathname.match(this._pathToRegex(route.path))
        }));

        let match = potentialMatches.find(potentialMatch => potentialMatch.result !== null);

        if (!match) {
            match = {
                route: this.defaultRoute,
                result: [location.pathname]
            };
        }


        const props = match.route.props;
        const params = this._getParams(match);
        const query = this._getQuery(location.search);

        DCL.params = params;
        DCL.query = query;

        // set view for determined route
        this.view = new match.route.view({...props, params, query});

        this._rerender();
    }

    render() {
        if(!this.view) return "";

        return `<div>${this.view.mount(this)}</div>`;
    }

    _pathToRegex = path => new RegExp("^" + path.replace(/\/?$/g, "").replace(/\//g, "\\/").replace(/:\w+/g, "([^/]+)") + "\/?$");

    _getParams = match => {
        const values = match.result.slice(1);
        const keys = Array.from(match.route.path.matchAll(/:(\w+)/g)).map(result => result[1]);

        return Object.fromEntries(keys.map((key, i) => {
            return [key, decodeURI(values[i])];
        }));
    };

    _getQuery = searchParams => {
        const urlSearchParams = new URLSearchParams(searchParams);
        const query = Object.fromEntries(urlSearchParams.entries());
        return query;
    };
}

The Router is a custom standard component that hooks onto the forward and backward navigation of the page and swaps out the component based on the path. The router can be used with the following code:

class TodoPage extends DCL {
    render() {
        return `
            <div>
                <p>ID: ${this.props.params.id}</p>
            </div>
        `
    }
}
class Main extends DCL {
    render() {
        const router = new Router({
            routes: [
                { path: "/", view: HomePage, props: { num: 5 } },
                { path: "/todos", view: TodosPage },
                { path: "/todo/:id", view: TodoPage },
            ],
            defaultRoute: { path: "/404", view: Page404 },
        });

        return `
            <div>
                <nav>
                    <a href="/" data-dcl-link>Home</a>
                    <a href="/todos" data-dcl-link>Todos</a>
                    <a href="/todo/4" data-dcl-link>4th Todo</a>
                </nav>
                ${new Header().mount(this)}
                    <main>
                        ${router.mount(this)}
                    </main>
                ${new Footer().mount(this)}
            </div>
        `
    }
}

Disadvantages of DCL

Although DCL solved all of my needs, it was not without bugs that I was not able to solve:

Code Smell:

Different sections of the core class is polluted with spaghetti code, as I gradually built upon DCL alongside Projectree. Some code chunks may be completely useless, but I have not removed it due to continual development.

Breaking Input:

One major unsolvable issue is how inputs are handled. If an onchange event was used with the <input> element that causes it to rerender every time a value was entered, after each character was pressed, the component would rerender the input and focus would be lost.

Currently, DCL tries to solve this using a hack: It tries to keep track of each selected element per click, and holds an XPath reference to that element. If the element is a textarea or input element, it stores the selection range.

Additionally, an observeDOM function is defined that waits for a change in the document using MutationObserver. When any component is rerendered, the DOM is considered changed, and DCL attempts to reselect the input element using the previously stored XPath.

Sometimes this works successfully, but this assumes the input element remains in the same location in the webpage. Oftentimes, another element in the document is added or removed arbitrarily, and the XPath causes some other element to be reselected (or an error occurs if no matching XPath is found), which breaks the user experience, as they type into one field and suddenly are typing in another input field.

Other times, if there are too many input elements on the page, the observeDOM tries to reselect an input field before the document rerenders every component, which also breaks user experience, since the input field suddenly loses focus.

I tried to create timeouts to wait a few milliseconds after rerendering before attempting to reselect elements, but this process also breaks for many elements. In the end, DCL currently has no way to determine when all elements have completely rerendered to attempt to reselect, which causes this issue.

DCL also accounts for asynchronous methods in its API, which makes detecting complete rerenders more difficult.

Wonky Paradigms:

DCL supports additional unmentioned options such as middleware functions that are called before each reroute, as well as ignoreRoute checks that can skip a route call if a condition fails (e.g. the user is not authorized). However, with the current flow of the application, sometimes the ignoreRoute is called after the incomplete view has rendered, causing a flicker on the end user's screen. I would have to rearrange some of DCL's routing logic to better control that flow, but it gets diffucult to control since each nested component is called using the _mount() method.

SEO Limitations:

As DCL is a single page application (SPA) framework, it is client-side rendered (CSR). A user launches the page and are greeted with the standard HTML template that is then populated into an application when the JavaScript loads. For users, this is assumed as the loading process and is experienced for a few milliseconds to a few seconds, depending on connection speed or other factors. However, web crawlers that index pages usually do not wait around those extra seconds for the JavaScript to be loaded.

Currently, as DCL is a minimal develop-as-needed framework with no build steps, I had not considered supporting server-side rendering (SSR) which would be ideal for search engine optimizations.

Conclusion

DCL is a develop-as-needed library that I no longer have plans of working on, however, it was very helpful throughout the development of Projectree. From this experience, I have reasons both for and against creating your own frontend framework.

Why You Should Create Your Own Framework

From working on DCL, I learnt more about the internals of an SPA, and became aware of more browser APIs that I did not know before (such as history API), that can be used to make the developer experience easier. It is thanks to this project that I am able to better appreciate existing frameworks; although each seem complicated, they try in their own ways to make the developer's experience better, and provide as many tools as possible to create web apps.

I believe a developer should strive to make their own framework to understand what happens underneath, as it can also help them understand existing frameworks more.

Why You Should Not Create Your Own Framework

The code and examples in this article are a simplified view of what DCL is, however, it still cannot compare to solutions existing frameworks solve, and features they already provide. Additionally, many groups of senior developers and architects work on existing frameworks, and cater for many more edge cases than DCL does.

While developers should create their own frameworks for the learning experience, unless they are senior developers with industry level experience, it would be better to learn and use an existing framework.

Unless they are also like me and are too stubborn to learn a new framework; though eventually, I too will have to learn new frameworks.

Eventually, I'd like to recreate Projectree's frontend using React or SolidJS instead. Hopefully it is an easier process since I have first-hand experience. Hopefully, I've also convinced you to try creating your own frontend library too. You know...for the fun of it.

And also for the learning experience 😉

Thanks for staying tuned each week for articles this writeathon! You can click the links below to support me or check the unofficial source code yourself:

• DCL: Source code
• Projectree: https://projectree.net
• Twitter: @danidre
• Patreon: Danidre

Happy learning!

If you want to skip straight to the tutorial section of this article, click here: How to create a custom implementation system in Fastify

Introduction

Last July, I participated in the PlanetScale x Hashnode Hackathon, and created Projectree using a custom JavaScript SPA library on the frontend, Django on the backend, and PlanetScale as the database. I had worked on the frontend, and teamed up with Sophia who worked on the backend.

Projectree is a service that you can use to create simplified showcases of projects you have worked on.

Since then, I had plans to continue working on Projectree, but unfortunately, Sophia was no longer able to continue working on it with me. Thus, I had to work on the backend myself.

Modifying Projectree's Backend

Sophia used Django and Django ORM for Projectree's backend. Honestly, I was able to scan the source code on GitHub and understand how she made everything work, but I had no idea how to begin restructuring everything to develop it for my specific plans and goals for Projectree.

I decided to remake Projectree's backend myself, so I could have full control of the stack, and understanding of how to further customize it. I told Sophia about it, who was quite supportive of the idea. I changed the existing projectree frontend domain to https://legacy.projectree.net and she enabled the Django backend's CORS for that domain.

The Django backend is actually deployed to Heroku with their free dynos, but by November 28th, this form of hosting will no longer be possible. By then, the Django backend will most likely be sunsetted as well.

Then I started recreating the backend.

Choosing a Stack

Projectree's plans exceeded the existing capabilities possible at the end of the hackathon, so to achieve them, I needed something I was familiar and comfortable with. My go to tech stack is NodeJS, Express, MongoDB, but I wanted to try something new as well.

For the new backend, I decided to use (and learn) NodeJS, Fastify, Prisma, and SQLite.

Why I chose each option

Fastify

Projectree's backend acts more like an API, that accepts requests and sends responses. Fastify is better suited for APIs since it is fast, and not as bloated as Express.

Prisma

One thing I passionately detested about SQL databases, is the migration process.

It was for this reason that I teamed up with a backend developer; they can battle with databases, and I will focus on the frontend.

However, most of the data in Projectree is relational, so a relational database would be a more suitable choice.

Prisma allows you to use many databases such as PostgreSQL and MongoDB, and it would manage database migrations, and changing schemas for you. Additionally, it provides very intuitive APIs for querying data, creating records, and much more.

SQLite

Although Prisma removes the tedious migration work for me, I still need to set up databases both locally and in production (whether I used MySQL, MariaDB, PostgreSQL, etc). I was trying to avoid that setup, and decided to use SQLite. It was boasted as being super fast, with no tedious setup, and can reside right in your application directory.

Many developers on discord advocated for its usage:

Creating an Auth System

Projectree's first backend used Django, and came with its own authentication system, which made developing easy, as it allowed for easy integration with the database using Django ORM. I needed to remake this in Fastify.

From previous projects, I only had experience with Express' Passport middleware for authentication, using its local strategy.

The local strategy allows you to authenticate using a username and password, rather than an OAuth method that uses Discord, Facebook, Twitter, Gmail, etc to sign in to the account.

At first, I tried looking for a passport middleware counterpart for Fastify or using a Fastify specific authentication library, but in the attitude of learning new things, I decided to learn how to implement authentication of my own.

What is auth?

Auth is used both when talking about authentication, and authorization. Authentication deals with determing the identity of the person making the request, and authorization deals with whether the authenticated person can perform a requested action or not.

Auth can be implemented in multiple ways such as sessions or JWTs, and each method has their pros and cons. For Projectree, I decided to use sessions.

The general idea

The server is generally able to determine who is making a request through some form of identifier. When the user logs in (is authenticated), they are assigned an identifier, which they use in subsequent requests. The server will verify that the identifier is valid while processing each request, and perform different actions based on whether the user is allowed (is authorized) to make that request or not.

My custom auth theory

Middleware like Passport allows for a session store (like a database) to store the session details of the users. However, as I was implementing my own auth, I did not want to additionally handle storing sessions in a database, setting schemas, etc. As a result, I opted for storing the session identifier in the client's cookie when they sign in (for authentication); and then checking that cookie per request for authorization. Then, when the client logs out, that cookie will be destroyed.

Trivia: I honestly do not fully understand how the server keeps track of the sessions for anonymous users, even. Maybe the existing libraries simply set and read cookie variables, so a repeating request identifies them. Maybe it involves the TCP handshake of the client and server, and they are able to recognize the client's subsequent request because...of magic?

Addressing Security Concerns

While this method seems simple, there are many flaws to it:

• Clients can modify their cookies, which means a malicious user can modify their session details to be someone else.
• Clients can read their cookies. Third party scripts would then be able to execute scripts that send cookie data to their own malicious data centers.
• Data can be accessible through http (unsecure) connections.
• Cross site request forgeries (CSRF) can occur where a bad site perform an action through your good site, which sends your cookies, and the server is unable to determine whether it is a legit authenticated request, or a forged authorized one.

To address these, I made the following configurations with the cookies:

• Enable httpOnly cookies. That way, only the server can access and modify the cookies.
• Enable secure cookies. That way, cookies will only be sent on https (encrypted) connections.
• Use a cookie secret. Existing libraries allow a cookie secret that can be used to sign the cookie. That way, the server will be able to determine whether the cookie was manually modified by another source than itself.
  
  Some libraries also garble the cookie data when signed, so it is not human readable; however, the general practice is to not store sensitive information in the cookie in any case.
• Set the sameSite attribute to "lax" or "strict". These help the browser decide whether to send cookies along with cross-site requests, which can mitigate CSRFs.

To distinguish between the Strict and Lax sameSite values, check this OWASP resource.

Implementation Code

The remainder of this article could be read more as a tutorial instead.

How to create a custom implementation system in Fastify

Unlike other tutorials that build a mini application along with the auth code, this one will simply focus on the auth code, with assumptions and pseudocode in other places.

0) Prerequisites

This tutorial uses NodeJS, so ensure you have nodejs installed.

1) Install the dependencies

For this tutorial, the main packages/modules you will need are fastify, fastify's secure session, and fastify plugin.

npm i fastify @fastify/secure-session fastify-plugin

• fastify: The web framework we are creating the API with.
• @fastify/secure-session: Creates a secure stateless cookie session for Fastify.
  • I chose this over @fastify/session because this module stores the session data in the client's cookie, instead of requiring a database like @fastify/session.
  • I also chose this over @fastify/cookie because the syntax of accessing and modifying the cookies with this library was easier than @fastify/cookie.
• fastify-plugin: A module that you use to allow your plugin to be accessible throughout the intended Fastify contexts.

2) Create your server file

Next, you create your main server file (server.js) and add the following code to it:

// server.js

const fastify = require("fastify");
const fastifySecureSession = require("@fastify/secure-session");

const secureSessionConfig = {
    secret: process.env.COOKIE_SECRET || "averylogphrasebiggerthanthirtytwochars",
    cookie: {
        path: "/"
    }
}
if (process.env.NODE_ENV === "production") {
    secureSessionConfig.cookie.secure = true // serve secure cookies
    secureSessionConfig.cookie.httpOnly = true // serve cookies only accessible by the server
    secureSessionConfig.cookie.sameSite = "strict"; // serve cookies only from site
}

const app = fastify({ignoreTrailingSlash: true});

app.register(fastifySecureSession, secureSessionConfig);

app.listen({ port: process.env.PORT || 3000 }, (err, address) => {
    if (err) {
        app.log.error(err);
        process.exit(1);
    }
    console.log("Server started on address " + address);
});

Here we have a basic Fastify server, with a few modifications in preparation for the custom authentication;

First we import fastify and @fastify/secure-session, and initialize them accordingly. Notice that we create a secureSessionConfig object with the options to use with fastify's secure session.

I added the ignoreTrailingSlash property so urls like example.com/home and example.com/home/ both point to the same request handler.

As explained before, we provide a secret to be used for signing the cookie, and in a production environment, we want the cookies to be secure, httpOnly cookies with sameSite "lax" or "strict". Additionally, we want the default path of the cookies to be at the root of the application.

Trivia: I originally left out this path property, but experienced unexpected behaviours in my application: Multiple session cookies were being set on different paths, making multiple users authenticated on the same device, depending on which endpoint was being fetched.

Then we start the server with app.listen.

3) Create your custom auth module

After that, we want to implement our custom authentication system. We will extend the functionality of Fastify's flow by managing the sessions set in @fastify/secure-session in this file. For that, we use fastify-plugin. Let's create a customAuth.js file in the same directory as the server.js file and add the following code:

// customAuth.js

const fp = require('fastify-plugin')
async function customAuth(fastify, options) {

    fastify.decorateRequest("user", null);
    fastify.decorateRequest("isAuthenticated", null);
    fastify.decorateRequest("logIn", null);
    fastify.decorateRequest("logOut", null);

    fastify.addHook("onRequest", (req, res, next) => {
        const getUser = () => {
            try {
                const user = req.session.get("user");
                if (user) {
                    return user;
                }
                return null;
            } catch {
                return null;
            }
        }
        req.isAuthenticated = () => {
            return !!getUser();
        }
        req.logOut = () => {
            req.session.set("user", undefined);
        }
        req.logIn = (data, cb) => {
            const done = function (error, user) {
                if (error) {
                    if (cb && typeof cb === "function")
                        cb(error, user);
                    return;
                }
                req.session.set("user", user);
                if (cb && typeof cb === "function")
                    cb(null, user);
            }
            try {
                if (customAuth.authenticate && typeof customAuth.authenticate === "function") {
                    customAuth.authenticate(data, done);
                } else {
                    if (cb && typeof cb === "function")
                        cb("Cannot authenticate. No authentication method found.", null);
                }
            } catch (err) {
                if (cb && typeof cb === "function")
                    cb(err, null);
            }
        }
        req.user = getUser();
        next();
    });
}

customAuth.useStrategy = (strategy) => {
    if (strategy && typeof strategy === "function") {
        customAuth.authenticate = strategy;
    }
}

module.exports = fp(customAuth);

As suggested by Fastify's Docs, decorateRequest is used to allow the underlying JavaScript engine to optimize the handling of the objects sent in the context of requests. Since we modify the request's user, isAuthenticated, logIn and logOut objects in our custom auth module, I decorate those on the request object.

The onRequest hook (fastify.addHook("onRequest"...) is where our custom authentication's value comes in. Fastify Hooks allow you to listen to specific events in the application, and we can use the onRequest hook to intercept each incoming request and modify it accordingly, before passing it on to the rest of our application to manage.

When each request is received, our custom auth checks the request's session user property to determine whether a value exists (getUser returns the user) or not (getUser returns null).

Afterward, we decorate the request with an isAuthenticated function that can be used in any later API handlers.

Then, we also add logOut and logIn functions that takes the applicable data and modifies the session with that authenticated user or not, so future requests will have that session's data in them.

Finally, we populate the request's user property with the specific user, again for easy usage in a later API handler.

Our unopinionated auth system

Our custom auth focuses on setting cookies when a log in was successful, deleting cookies when a log out was called, and allowing later request handlers to get the requesting user's details. It does not determine how to authenticate the user. That is left up to the developer to decide.

For that, our custom auth exposes a useStrategy function, where the developer passes a stragety for authenticating a user. This is where the developer can check their database, compare encrypted passwords, and more. When successful, the developer can call the done function provided in the logIn method, which will authenticate the user and run the specific callback function (where the developer can redirect to another page, for example). If the first parameter is truthy, it will be considered an error, and that would mean the authentication failed. Otherwise, the authentication should be successful and the session's user property will be the data provided in the second parameter.

4) Use the custom auth in our application

Now that we have created the module, let's import and use it in our server.js file:

// server.js
const fastify = require("fastify");
const fastifySecureSession = require("@fastify/secure-session");
const customAuth = require("./customAuth"); // < added line

// .. other code

app.register(fastifySecureSession, secureSessionConfig);
app.register(customAuth); // < added line

Important: Since our custom auth module relies on req.session, it is important to register fastify's secure session module before our custom auth module.

Next, let's initialize our custom auth strategy before attempting to use it in our request handlers:

// server.js

app.register(fastifySecureSession, secureSessionConfig);
app.register(customAuth); 

// added chunk
customAuth.useStrategy(async (data, done) => {
    const { username, password } = data;
    try {
        const user = await database.user.find({username, password}, {id, username, password});
        if (!user)
            return done("User does not exist");

        if(passwordVerifier.verify(password, user.password)) {
            return done(null, { id: user.id, username: user.username });
        } else {
            return done("Username or password incorrect");
        }
    } catch (err) {
        return done(err);
    }
});

app.listen...

Our strategy will accept a username and password, and compare it to existing data in a database of our choice, then verify the matching passwords and call done based on whether the user was found with a matching password (user authenticated) or not (user not authenticated).

For validating passwords, you can use packages like bcrypt.

Finally, let's create some routes that uses our auth system:

// server.js

app.post("/signin", (req, res) => {
    if (req.isAuthenticated()) {
        res.send({ message: "Already signed in" });
        return;
    }
    try {
        const { username, password } = req.body;

        req.logIn({ username, password }, (error, user) => {
            if (error) {
                res.send({ error });
            } else {
                res.send({ success: true, user });
            }
        });
    } catch {
        res.send({ message: "Sign in failed" });
    }
});

app.post("/signup", async (req, res) => {
    if (req.isAuthenticated()) {
        res.send({ message: "Already signed up" });
        return;
    }
    try {
        // validate request

        // .. other code
    } catch {
        res.send({ message: "Sign up failed" });
    }
});

app.delete("/signout", (req, res) => {
    if (req.isAuthenticated()) {
        req.logOut();
        res.send({ success: true });
    } else {
        res.send({ message: "Already signed out" });
    }
});

app.listen...

Since these requests handlers are defined after the authentication module was imported, registered, and strategy initialized, each handler has access to our custom auth's decorated properties.

Sign In Code Explanation

In the sign in handler, we first check to see if the user is already logged in, using the decorated req.isAuthenticated method. Internally, the custom auth module checks the session properties for that existing cookie and returns true or false on whether it exists.

Then, we call the req.logIn method, passing the username and password we want to use in our authentication strategy we defined above. Internally, the custom auth module executes our authentication strategy, comparing the information to what we have in our database, just like we set it to.

In the req.logIn callback, we also handle the response provided by the internal done function; If no user exists, the error is sent to the user. Otherwise, a success response is sent, as the user is signed in. If the log in is successful, internally, the custom auth sets the session's user property to be that user, so that cookie value will be included in future requests, and the server will be able to determine that the user is authenticated correctly.

Sign Up Code

This one is left up to the developer's implementation, but note that I use the req.isAuthenticated method again as part of the request handling flow. In this case, logged in users are not authorized to create new accounts; we do not want to handle signing up a user when they are already logged in.

Of course, depending on your application, you can omit this code block.

Sign Out Code Explanation

This request handler is simple; it calls the decorated req.logOut method if the user is logged in. Internally, the custom auth module will delete the session's user properties, so the cookies won't exist on future requests.

Tutorial Conclusion

There you have it! Your own custom authentication system in under 100 lines of code, that allows you to define your own authentication strategy, and manage authorization in your request handlers.

Here is the full code (and pseudocode) for review:

server.js

const fastify = require("fastify");
const fastifySecureSession = require("@fastify/secure-session");
const customAuth = require("./customAuth");

const secureSessionConfig = {
    secret: process.env.COOKIE_SECRET || "averylogphrasebiggerthanthirtytwochars",
    cookie: {
        path: "/"
    }
}
if (process.env.NODE_ENV === "production") {
    secureSessionConfig.cookie.secure = true // serve secure cookies
    secureSessionConfig.cookie.httpOnly = true // serve cookies only accessible by the server
    secureSessionConfig.cookie.sameSite = "strict"; // serve cookies only from site
}

const app = fastify({ ignoreTrailingSlash: true });

app.register(fastifySecureSession, secureSessionConfig);
app.register(customAuth);

customAuth.useStrategy(async (data, done) => {
    const { username, password } = data;
    try {
        const user = await database.user.find({ username, password }, { id, username, password });
        if (!user)
            return done("User does not exist");

        if (passwordVerifier.verify(password, user.password)) {
            return done(null, { id: user.id, username: user.username });
        } else {
            return done("Username or password incorrect");
        }
    } catch (err) {
        return done(err);
    }
});

app.post("/signin", (req, res) => {
    if (req.isAuthenticated()) {
        res.send({ message: "Already signed in" });
        return;
    }
    try {
        const { username, password } = req.body;

        req.logIn({ username, password }, (error, user) => {
            if (error) {
                res.send({ error });
            } else {
                res.send({ success: true, user });
            }
        });
    } catch {
        res.send({ message: "Sign in failed" });
    }
});

app.post("/signup", async (req, res) => {
    if (req.isAuthenticated()) {
        res.send({ message: "Already signed up" });
        return;
    }
    try {
        // validate request

        // .. other code
    } catch {
        res.send({ message: "Sign up failed" });
    }
});

app.delete("/signout", (req, res) => {
    if (req.isAuthenticated()) {
        req.logOut();
        res.send({ success: true });
    } else {
        res.send({ message: "Already signed out" });
    }
});

app.listen({ port: process.env.PORT || 3000 }, (err, address) => {
    if (err) {
        app.log.error(err);
        process.exit(1);
    }
    console.log("Server started on address " + address);
});

//customAuth.js

const fp = require('fastify-plugin')
async function customAuth(fastify, options) {

    fastify.decorateRequest("user", null);
    fastify.decorateRequest("isAuthenticated", null);
    fastify.decorateRequest("logIn", null);
    fastify.decorateRequest("logOut", null);

    fastify.addHook("onRequest", (req, res, next) => {
        const getUser = () => {
            try {
                const user = req.session.get("user");
                if (user) {
                    return user;
                }
                return null;
            } catch {
                return null;
            }
        }
        req.isAuthenticated = () => {
            return !!getUser();
        }
        req.logOut = () => {
            req.session.set("user", undefined);
        }
        req.logIn = (data, cb) => {
            const done = function (error, user) {
                if (error) {
                    if (cb && typeof cb === "function")
                        cb(error, user);
                    return;
                }
                req.session.set("user", user);
                if (cb && typeof cb === "function")
                    cb(null, user);
            }
            try {
                if (customAuth.authenticate && typeof customAuth.authenticate === "function") {
                    customAuth.authenticate(data, done);
                } else {
                    if (cb && typeof cb === "function")
                        cb("Cannot authenticate. No authentication method found.", null);
                }
            } catch (err) {
                if (cb && typeof cb === "function")
                    cb(err, null);
            }
        }
        req.user = getUser();
        next();
    });
}

customAuth.useStrategy = (strategy) => {
    if (strategy && typeof strategy === "function") {
        customAuth.authenticate = strategy;
    }
}

module.exports = fp(customAuth);

And that's it! Now you know how to implement custom authentication in your own application!

Trivia: If you are familiar with Passport, many of the exposed decorated functions may look similar, and that is because...again...most of my prior experience with auth is using Passport and its local strategy.

Some topics were not covered in the tutorial, such as hiding sensitive environment variables (using packages like dotenv), or other best practices, because that was not the focus of the tutorial. However, do be sure to follow such best practices in your own projects.

Theory Refresher

Auth is about determining who made the request, and if that person is allowed to perform an action or not. We authenticate our users by storing their ID in a secure, httpOnly cookie, signed with a secret, and CSRF mitigated with a "lax" or "strict" sameSite value. Then, we created an unopinionated authentication system that accesses and modifies those cookies for us, and provides functions for us to use in our request handlers to determine how to authenticate and authorize users ourselves, no matter what databases or flow we use.

The benefit of this theory is that, even if you are using another NodeJS web framework (such as Express) or another language entirely, you'll be able to follow along and create your own authentication system.

Assurances

As a developer that switched from primarily using an authentication library to creating one myself, you may wonder whether my custom implementation may have flaws the existing libraries covers/fixes?

However, before attempting this implementation, I had 2 years prior of implementing authentication in different applications, where I mostly used PassportJS. For this library, I took about 2 weeks researching the topic, which involved reading blogs, articles, and documentation on authentication, discussing it with Discord peers, watching YouTube Videos, and more. I also took a look at the source code of the @fastify/passport module, and surprisingly enough, it is very similar to how I implemented auth myself. Thus, I am a bit certain about what I've created.

And if I am completely wrong, please feel free to educate me! 🙏🏾

Disclaimers

Authentication always seems easy, but there are a few gotchas that have terrible consequences if you are not aware of them. It is possible that I have not covered all cases either, so please let me know in the comments.

While assured, this code has not been battle-tested in a production environment for robustness. I encourage you to do your own additional research before creating your own authentication systems as well. For that, I generally recommend reading the various OWASP resources. There are many more layers of defense that can be implemented (such as CSRF Tokens) to protect users in a more robust way, and such resources can help guide you.

Alternatively, I encourage you to use an existing battle-tested auth library instead.

Conclusion

After implementing authentication of my own, I was able to continue working on Projectree's new backend. Since I decided to learn new tools, I spent about a month rewriting the backend to bring it up to the current Django version. The results from the hackathon have already been released; I no longer need to keep it on PlanetScale's databases, so I've deployed it on Linode.

Unfortunately, our project did not receive a winning prize in the hackathon, so when Heroku's free dyno tiers end, we will not have the funds to support it on a paid tier anyways, so the change in deployment was the more convenient decision.

I plan to continue working on Projectree in the future, so feel free to check it out and use it!.

Stay tuned throughout the next 2 weeks for more articles like this!

Thanks for reading!

To many developers (like me), software development involves brainstorming problems, implementing solutions, and of course, debugging errors. Inevitably, there may be a breaking change that needs fixing, and sometimes, systems crash entirely, because the developer is unable to find the errors or debug the issue.

Here are the top 4 things I do when stuck during development:

1. Retracing my steps

I always check the error messages to see what broke. In frontend development, I use the browser's developer tools to monitor the logged errors. In backend development, the terminal generally has the error messages. Most times, the error message tells you exactly what went wrong.

Browser error message, telling me I've made a syntax error.

Terminal error message, telling me a variable is not defined.

Many times, I spelt a variable incorrectly (fooo instead of foo), or missed a semi-colon at the end of the line. These are syntax errors, and can easily be solved when identified; and I can continue development quickly.

2. Researching the issue (documentation, stackoverflow, forums, etc)

Oftentimes, the incorrect use of imported libraries can cause the errors. Sometimes, a simple quick fix is not readily available, as the developer does not know how to use the library's APIs correctly.

Error trying to find all records using prisma.

When I'm stuck with errors from an API, I google search the library or package and browse multiple links on the topic. For example, if I forgot the proper syntax for creating a record in prisma, I enter the following search:

From there, I check the documentation, Stack Overflow discussions, or GitHub forums for proper references and guidance. Most times I leave with much more knowledge than I was looking for, such as how to create a record and update it too.

I also use google when searching for algorithms or other functions I may need, that are too complex to retype every time. Maybe I already implemented a remainder function but realize that it moves slow. Googling existing remainder functions in the language of my choice can bring a much more optimized code snippet that I can use to speed up my own application.

My first ever implementation of a remainder function:

function remainder(dividend, divisor) {
    if(dividend == divisor) {
        return 0;
    } else if(divisor == 0) {
        return divisor;
    } else if(dividend == 0) {
        return 0;
    } else if(dividend > 0) {
        divisor = Math.abs(divisor);
        while(dividend >= divisor) {
            dividend -= divisor;
        }
    } else if(dividend < 0) {
        divisor = Math.abs(divisor) * -1;
        while(dividend <= divisor) {
            dividend -= divisor;
        }
    }
    return dividend;
}

A similar function found while searching:

function remainder(dividend, divisor) {
    return dividend % divisor;
}

Of course, I "generally" did the research to understand the optimized code before I used it in my own work.

3. Manually debugging code

Sometimes, even without syntax errors, your program would not work as expected. Either your function to perform a calculation returns a NaN or Infinity value, you are redirected to an arbitrary page, or your application generates additional fields unexpectedly because you put <= instead of < in a for loop. These can all be caused by logic errors or runtime errors.

When researching or reading error logs do not work, I add breakpoints to my code to interactively see the different values to understand where it went wrong. Can you determine why my add function returns 20 instead of 9 when I input 4 and 5?

function addTwoNumbers(num1, num2) {
    let sum = num1 * num2;
    return sum;
}

If you realized I put the wrong operator, you guessed correctly. It did not give syntax errors, but the application did not work as intended. Adding breakpoints and then monitoring each line can help find logic errors and get your functions working again, so you are no longer stuck.

Debugging Trivia (Shameful Disclaimer)

While I do use breakpoints, I find it easier (and faster) to log my variables in the function and then monitor the console for the specific values:

function addTwoNumbers(num1, num2) {
    console.log("Num1 is " + num1);
    console.log("Num2 is " + num2);

    let sum = num1 * num2;

    console.log("Sum is " + sum);

    return sum;
}

let nine = addTwoNumbers(4, 5)

// Console prints:
// > Num1 is 4
// > Num2 is 5
// > Sum is 20

From the console, I notice the sum was incorrect, which prompts me to check sum assignment expression and realize I wrote * instead of + in the statement.

4. Exploring communities like Discord

When learning to develop, I joined Discord servers such as Web Dev Simplified and Nodeiflux and spent lots of time asking questions there. Many helpful developers assisted in real time debugging and problem solving.

Disclaimer (Being Spoonfed)

While it is helpful to have instantaneous assistance, try to use this option as a last resort. Making mistakes and learning how to solve them is important to a developer's growth and learning. At the beginning I spammed questions for every small issue, but soon realized that I would only depend on others, and not learn anything myself, so I tried solving problems myself before asking for an answer right away. I have actually been able to solve the issues myself without needing assistance!

As time passed, I have been able to give back to these communities by answering questions myself, helping other developers that may be stuck themselves.

Minimizing Errors and Increasing Development Productivity

During development, causing bugs or getting stuck is inevitable. However, with the right tools, sufficient practice, and patient preparation, you can reduce the amount of bugs that may appear in your code, and get stuck less. That way, you can spend more time working on your applications, and less time debugging or being stuck.

Here are 2 tips for decreasing the chances of getting stuck while you code:

1. Spend time brainstorming your problem before implementing it

An important part of development is design; understanding what you are developing as well as what is needed for it. Generally, I spend more time thinking about how I will implement a feature, than I spend actually implementing that feature.

Discuss it with peers

Usually, I request feedback on proposed solutions by asking classmates, talking to discord helpers, or publishing discussions on forums. Sometimes, they share knowledge that benefits me; whether it is a different perspective, a more efficient function, or an existing tool that already solves my problem.

Write it down on paper

I also like breaking down steps on paper to mockup what needs to be achieved, often with pseudocode to help. For my game engine, I often spent weeks designing or constructing an idea or feature, and then when it was time to implement it, I did so in a few days.

The benefit of planning in advance is that you have enough time to think of many general edge cases, and when you get to coding, you implement the feature faster. Also, since you are may already have pseudocode, you can end up with less errors, as you are not instantly coding from your head and thinking of fixing unexpected cases afterward.

Spending lots of time planning first before implementing is not suitable for all development environments; you still spend time on the application. However, that time is spent productively designing and developing, rather than developing and then trying to debug and fix crashes and errors.

2. Use statically typed languages

With dynamically typed languages (such as JavaScript or Python), type checking occurs at runtime. It is easy to write logically incorrect code, such as attempting to subtract objects from integers. While these assignments may not result in syntax errors all the time, they do result in logical errors that are only discovered at runtime.

With statically typed languages (such as TypeScript or C++), type checking occurs at compile time. The benefit of this is that you are warned in advance of any possible unintended expressions that can result in hard to discover bugs. This increases productivity as well, since less time is spent finding bugs later on.

Bonus Advice

It is okay to fail

Even with all those steps and tips, you can still get stuck:

• maybe the error message is not helpful at all;
• maybe google has no searches recorded for the issue;
• maybe debugging code and creating breakpoints shows no abnormalities;
• maybe no one on Discord can help you with your issue either;
• maybe after days preparing your solution, implementation fails, and you have to re-plan everything;

That is okay, and to that I suggest taking a break, and trying again at another time. Maybe you may be able to solve it in the future.

In production environments where deadlines are impending, professional advice would be to reach out to a senior for assistance; it is better to admit your shortcomings and seek assistance earlier, than keeping quiet until deadlines where everything is in a rush.

Conclusion

These are all steps that have continued to work for me as a software developer. Of course, it gets frustrating when you are stuck, and I blame the software occasionally, but eventually, I have always been able to solve my problems and proceed with my software development.

It is always a refreshing thrill when your code finally works again!

Stay tuned throughout the next 3 weeks for more articles like this!

Thanks for reading!

Many people see software development as an avenue to easy money. Lately, with the drive of "anyone can code" promoted by major companies, this holds true even more. People run with this naive misconception that they can attend a 4-6 month coding bootcamp and then land a 6 figure job.

And sometimes, this holds true, and I'm always amazed by such people.

But oftentimes, I witness people entering discords and asking questions because they just completed a course and landed a job, but do not know how to accomplish what is being asked, and fear they will get fired soon.

Impostor syndrome; it haunts me to this day.

What makes a software developer

I believe developers should have a strong love or passion for what they're doing. Of course, for some people, programming really is just a job they do while at an office. But many developers I look up to are always tinkering and dabbling away during their spare time, participating in discussions on the direction of software, working on the open source software themselves, and more. Many of them have beginner stories of what inspired them to become developers, which includes programming as a child, or wanting to learn how to make a game or service for themselves or a close one.

And my story is no different.

What got me into software development

I always used to draw random games in primary school, and funny enough drew a 2D version of Minecraft in checkered-line books back in Standard 5 (grade 5).

I do not remember if it was inspired by Minecraft of not, since that was in 2010.

Fast forward to 2013 in Form 2 at secondary school (grade 7), my little bother found a 2D minecraft game called Mineblocks created by an amazing developer called Zanzlanz. As a hardcore fan, I found an option to contact him and sent him spam mail about how I can go about creating my own games.

Prior to this, I also did the same to Notch, to no avail. So I had no big hopes Zanzlanz would respond either.

Fortunately, what followed was him linking me to his YouTube and me watching his "How to Create 2D Minecraft in Flash".

Trying Development Myself

Before actually getting a response though, I remember being in the vehicle one day from school playing Mineblocks locally on my laptop and testing out GameMaker. I had tried the tutorial at the time, but at the end had no idea how to continue on my own. With Zanzlanz's tutorial on YouTube, what followed was a series of me googling "How to make racing game in flash", "How to make shooting game in flash"... basically "How to make x in flash". Furthermore, I even began googling more of "How to create 2D Minecraft" and saw a series in Java by Ulixava.

As you can see, I was really obsessed with Minecraft clones.

Understanding Programming at Last

What followed (again) was about a year or 2 of me copy pasting code from YouTube tutorials, first in flash, then in Java. One day, I returned to flash, looked at the code...and just...understood...what it did.

Since then I've branched off from game development alone to web development and (since Flash support ended) it was easy to adopt the JavaScript language for my games. Then recently, as I completed highschool and entered college, I branched off more into full stack development, first watching videos from a creator named Kyle on his WebDevSimplified YouTube channel, checking out courses on freecodecamp, and much more.

How I Continue to Learn

During learning and development, I joined Discord servers for assistance, and gradually became a member assisting others. Having to explain how/why something works to others, as well as debugging with them, has helped give me a greater understanding of things I may not have been able to figure out on my own.

Since then, I've also participated in hackathons, building open source software that can be useful to others, such as endpoint loggers, and game engines. That was when I realized, I prefer making tools that can be used to make creations. That was when I realized I may be a software architect.

Additionally, recently I became an intern, and although I only knew NodeJS, it had been fairly easy adopting PHP, Python, some Vue, and more.

Sources of Inspiration

I'm always interested in how software works, and am inspired by those that build such software. For example, I was incredibly amazed by Tanney Linsley in React Summit, 2022. He built react table over 5 years, adopting Typescript over 2 years, and now moved on to TanStack Table, a framework agnostic version of what he started building 5 years ago!

His passion and love for development consistently radiated through his spectacular presentation, which inspired me much more to one day be developing projects on quite a scale as his.

Conclusion

It is completely valid to become a programmer, get a programming job, and aim for a 6-figure salary. However, software developers that love and have a passion for what they do, make remarkable contributions to everyone, regardless of salary.

I still have some years before I get to that level, with entering my final year in University, participating in more hackathons, or working on more hobby projects, but gradually I hope to contribute greatly to open source myself. One day, I hope to continue game development as well, since that is what I originally started with.

Stay tuned throughout the next 4 weeks for more articles like this!

Thanks for reading!

Projectree is a service that you can use to create simplified showcases of projects you have worked on.

Create and showcase your projects lists without the hassle of building it yourself. Just add your project details, choose a theme, and generate!

Creating a projectree is as simple as entering the information for each project, choosing a predefined theme, and generating the project! You can then download your generated projectree and host it on your own site.

Projectree was developed by Sophia and me (Danidre) for the PlanetScale x Hashnode Hackathon, where the main criteria involved using PlanetScale as the database.

How Projectree Qualifies for the Hackathon

What I described so far is a tool that lets developers create and download their mini project showcases. A simple tool, right? Thus, you may ask: "Where is the database involved?"

Additional Features

By default, Projectree can only create and edit one projectee for users on that browser. However, if developers want to save multiple projectrees (for different purposes), they can do so by creating an account. Signed in users have access to a dashboard overviewing all their projectrees, where they can tweak each individually.

Even More Features!

With a Projectree account, developers can also host their projectrees directly on the website for others to view.

In Summary

User accounts, authentication, multiple projectrees, published projectrees... all these features require the database, which qualifies this project for the hackathon, as we use PlanetScale as this database.

Features

Creating a Projectree

To create a projectree, a developer can navigate to the /create route and begin editing. There, they can enter the details of their projectree, add project items, and customize those items, entering the project's name, description, languages used, source repository link, and demo site link.

Additionally, developers can add photos to the projectree by pasting existing links of photos.

There are plans on the roadmap to allow developers to upload their own photos, hosting them on cloudinary or uploadcare.

After the developer enters the data, they can choose an existing theme from which the projectree will be styled and generated.

Target Audience

While doing market research on the need for such a project, a FANG interviewer said that they would instantly skip a generated portfolio for a frontend position. I also believe that frontend developers/designers should develop their own portfolios and take the opportunity to showcase their skills.

Benefits for developers

Projectree may be most useful for fullstack, backend, devops, or other relevant positions where the focus of their work is not on the display of their design skills. If they still want a tool to quickly showcase their projects (without having to click into every GitHub repository, for example), Projectree can help. The showcase can display what the project is about, before checking out the repositories, allowing the viewer to decide whether to look further on any one project that catches their eye.

Built With

Projectree is a tool that allows developers to create project showcases, host it for them, or allow them to download it and host it elsewhere. Seems like a pretty simple application, right? However, it's not!

While accustomed to full stack development, I generally despise the database and deployment side of development. Thus, I partnered with Sophia for this hackathon. The agreement was that Sophia would work on the backend, connect to the database, deploy it, and provide APIs for me to consume on the frontend.

Frontend Stack (Danidre)

Langauges and libraries used

• HTML
• CSS (using Twind; for styling)
• JavaScript (using DCL)
• Netlify (for hosting)

Why I used them

I just planned to create something simple; nothing complex. I just needed some HTML, CSS, and JavaScript, and would use many fetch requests to the backend. But I would not be serving multiple views from the server, as everything would be client side. However, I still wanted the flexibility of reusing multiple components (like navigation bars and footers) without duplicating the code on separate frontend pages.

Additionally, I could not choose between React, Svelte, Solid, Vue, Handlebars, Pug, or other libraries and frameworks. React and other libraries come with the complication of requiring build tools or bundlers to compile or transpile code. I just wanted something I could drag and drop into Netlify, and it would work! Thus, I decided to create a library myself!

Because who gives up on an opportunity to learn something new!

I called it DCL, short for Danidre's Client Library (for lack of better name) and it has its own routing system, component nesting, event listeners, global states, and more.

All in all I probably spent 60% of the frontend work developing DCL, and the other 40% developing the frontend for Projectree, using DCL.

A lot of nights were spent teeth grinding and bug solving DCL errors that made me wish more and more than I used an existing framework...but... did it for the learning experience 😌

For styling, I used Twind, the smallest, fastest, most feature complete tailwind-in-js solution in existence. With this, I did not need PostCSS (which includes a build-step) which benefitted the Netlify drag and drop model I wanted.

In Summary

I wanted something simple; nothing complex. I did not need React or anything else that required bundlers and extra steps. In the end I created a mini library that caused headaches throughout development, but I'm really proud of what it turned out to be.

There is no official public repository dedicated to DCL yet, but you can check it out in Projectree's source code.

Backend Stack (Sophia)

Langauges and tools used

• Python (using Django & DjangoRest Framework; for API)
• MySQL (using PlanetScale; for database)
• Heroku (for deployment)

Why I used them

The backend structure is built using Django and Django rest framework. I used the framework to build the API (Application Program Interface) that connects the frontend to the database. I used Django because it is robust and easy to use; in addition, every API built using Django is very secure.

Since Projectree is a simple web app, it was easy for me to build and secure users' data. I chose Django because building API with its framework is easy and creating secured APIs and optimizing the database using Django was smooth for me.

The user authentication system on the backend is built based on JWT Authenticatication and each user uses a bearer token to create, edit, delete and view projectrees, project items, and published projects. Once the token expires, the user is logged out and must log in again to continue accessing advanced services on Projectree.

Building this project gave me a better insight into the authentication and authorization of Django and its framework. I talk about authentication because without that, the backend system and database would be exposed to malicious users. I believe security is the major thing to consider when building a backend system. Always validate. Never just trust the client.

In Summary

It was an exciting journey learning about how Django works and the way authentication and APIs work. Django being robust, SEO optimized, rapid, easily scalable, and versatile were my main reasons for choosing the stack for this project.

Development Roadmap

Projectree aims to be simple enough to use that a developer can create their project showcase in as little as 5 minutes. For that, the features prioritized were minimal proofs of concept, with future plans for features than can enhance the user experience of the service:

• [x] v 0.1

  • [x] 💻 Set up a single page application
  • [x] 💻 Develop custom frontend library
  • [x] 🗄️ Set up a django application
  • [x] ⚙️ Add readmes and licenses
  • [x] ⚙️ Determine database models and schemas
  • [x] ⚙️ Plan API routes
  • [x] ⚙️ Set up github repos

• [x] v 0.2

  • [x] 💻 Make "Create Projectree" prototype page
  • [x] 💻 Develop a standard theme for projectrees
  • [x] 💻 Allow users to download generated projectree
  • [x] 🗄️ Set up local database
  • [x] 🗄️ Develop register/login authentication

• [x] v 0.3

  • [x] 💻 Create sign up, sign in, and dashboard pages
  • [x] 💻 Make "Create Projectree" prototype page
  • [x] 💻 Deny or allow access to pages based on user authorization
  • [x] 🗄️ Create projectree models
  • [x] 🗄️ Develop REST APIs for projectrees
  • [x] 🗄️ Add route validation based on user authorization

• [x] v 0.5

  • [x] 💻 Create and style landing page, 404 page, and remaining pages
  • [x] 💻 Host frontend on Netlify
  • [x] 🗄️ Connect to planetscale database
  • [x] 🗄️ Test all API routes locally
  • [x] 🗄️ Deploy backend to Heroku

• [x] v 0.6

  • [x] 💻 Add meta tags for SEO
  • [x] 💻 Create page to view published projectrees
  • [x] 💻 Add privacy policy and tos pages
  • [x] ⚙️ Connect frontend to backend
  • [x] 💻 Add more predefined themes users can choose for their projectrees

• [ ] v 0.7

  • [ ] 💻 Use modals for alerts, prompts and confirms instead of browser natives
  • [ ] 🗄️ Add email confirmation when registering
  • [ ] 💻 Allow users to upload their project images instead of using a link only
  • [ ] 💻 Add user profile dashboard
  • [ ] ⚙️ Allow users to reset passwords
  • [ ] 💻 Allow exporting and importing projectree drafts as json

Challenges Faced

While Projectree seems like a really simple project, the challenges we faced during development took us the entirety of the month to complete it!

Frontend Challenges (Danidre)

I spent majority of the time working on DCL (Danidre's Client Library) for everything to work. Most of my challenges involved tweaking its source, fixing bugs that broke everything, and adding features that would make development easier for me. These include the following:

Creating a Router for Pages

I originally started off with this code on YouTube to create an SPA (single page application) with just JavaScript. I made use of history push and pop state so that the page would not have to refresh on every link clicked.

Creating Nested Components

Afterward, I modified the code to make everything a component. That way, they can render other components by looking for the returned html in each.

Handling State Changes

When state changes in a component, it needs to rerender everything in it to reflect the updated state. Instead of using a Virtual DOM (like React), I opted to wrapping each component in a fragment div by default, with unique dataSet IDs to identify those components alone. Then, the classes and dataSets are passed from that wrapper div to the main element returned for that component.

When it is rerendered, the element is first found on the page by the dataSet ID, rerendered with the wrapper, and then swapped to the child again, where the wrapper is removed again. This way, the wrappers do not break the intended developer's html semantics, as they are used just for rerendering, and then removed.

Handling Global Changes

Similar to React's useContext, DCL uses context in a publish/subscribe model, where components can monitor changes of specific context values from the global application, and rerender based on that global change.

Handling Focused Inputs

React has onchange handlers for input components that set the state as it is entered by the keyboard. However, when the components are then rerendered in DCL, the selected component is deleted and recreated, thus focus is lost. To regain the illusion of focus, DCL "remembers" the last component selected using the html's XPath, and after rerendering, tries its best to find and focus that element again. It also remembers the point in the input element that was selected, and reselects it, maintaining the focused element even when input changes.

Preventing Leaving Unsaved Changes

DCL also has a beforeNavigate event that the developer can use to prevent the page from being left (or reloaded) if data is not yet saved.

Ignoring Certain Routes

DCL also has an ignoreRoute method that can be called inside any component to skip rendering that page. For example, if a logged out user tries to navigate to the dashboard, the route will be ignored and the Error 404 page will appear instead.

In Summary

All these features were worked on side by side with the development of Projectree itself. During each hurdle, I wished more and more that I used an existing library that already solved these challenges, but in the end I am very proud of what I managed to create, and how fast it works!

It is plain JavaScript, after all.

Backend Challenges (Sophia)

I spent my time sketching the database (DB) schemas and thinking of the best way to design the database so that requests are seamless and fast. Unfortunately, I had lots of bumps on this development road and had lots of challenges fixing bugs. Deploying the backend with PlanetScale was the most challenging:

Pushing to PlanetScale DB

After extensive development, I finally realized PlanetScale DB does not support foreign-key constraints. It was a bit difficult for me to return to the drawing board and re-design everything. After that, deploying the backend to Heroku took me a week to solve because Heroku could not recognize the django_psbd_engine:

I had to clone another open source project to help me understand what I did wrong and how I can resolve that. In the end, the error was caused because I did not set the wrapper correctly around the database settings in the backend's settings.py file.

Thanks to Brian from the Developer Education team at PlanetScale for his support and assistance in deploying to Heroku.

Building a Custom User System

When Danidre brought up this idea, I made it a mission to build a custom user authentication system rather than using Django's packages such as django-allauth, or djangrest-routes.

It was a bit difficult because I had no idea what to do or where to start, so I read some articles and watched videos explaining how to start building a custom user model and securing the model using authentication and authorization. I finally got it right the third day!

...and then came the errors and bugs...

In Summary

All features are currently working successfully! It may not be as professional as full fledged APIs in enterprise projects, but I loved the experience, the thrills I got, and the excitement I got from every fixed bug or error. In the end, I am super proud of the system I built and its level of security; sometimes I can't believe I wrote this!

Running and Deployment

Check the GitHub Documentation on deploying a fork of Projectree.

Conclusion

Projectree aims to allow the quick creation of project showcases. We hope you find it useful!

See the links below to support us or check the project out yourself:

• GitHub: Frontend | Backend
• Application Link: https://projectree.net
• Twitter: @danidre | @sophiairoegbu_
• Patreon: Danidre

After participating in my first Write-a-thon, I proceeded with development as usual. One day, Hashnode announced another Hackathon, this time partnering with Linode, a cloud hosting company that provides virtual private servers.

The challenge was to create an open source project using Linode in some way or another, and attribute both Hashnode and Linode in the project.

At first, I wanted to dismiss the challenge as out of my scope. Learning new technologies always brings you back to a level of inferiority when things don't work, especially when you get by just fine with the tools you're already accustomed to. Even when I checked out their website, I was overwhelmed by everything they provide: higher education, ddos protection, saas...what did they all even mean??

I spent a day reading articles and watching YouTube videos on Linode, until I realized one thing I could use Linode for: deploying a NodeJS application. As a Windows developer, I mostly used services to deploy my apps (such as Heroku and CapRover). However, I recently gained experience with using Linux machines (Ubuntu 20.04) to manually deploy apps during my development at my summer internship.

Thus, all I needed to do was create an application locally, get a Linode virtual private server (vps), and deploy the app there.

In this particular case, I definitely planned to refer to the YouTube videos for assistance when deploying.

The only thing left to do was get an idea of an open source software to work on.

Getting an Idea

Idea generation involves many steps, from market research, to brainstorming, to finding problems that you can create a solution to. I had been stuck on this for a while, until I found a problem during my internship that at the time I could not seem to solve.

Having a Problem

Have you ever needed to integrate software to a server, where you do not have access to the server logs, and no control over what the external API sends to the server?

In my case, the external service would send a request to the server with data when triggered by an external action. Unfortunately, I had no easy way of determining the values being sent in the request, because their documentation was vague. Additionally, I may have been able to replicate the server locally, but I had no clue how to broadcast my IP for the service to send the request there instead (nor did I want to do something potentially unsafe, security-wise).

Finding a Solution

Thus, I wondered if there was a service one could use online to generate an endpoint for them, and they could use that in the external service. That way, when the requests are triggered, they can see what request was made and what data was sent. Unfortunately, I could not find any existing software to do it for me at the time, so I proceeded to make my own!

Me being unable to find existing software was due to me not knowing what to search for at the time. During research and development of 10 Minute Endpoint, I realized I should have searched words like "webhooks", and found Webhooks.site, an existing service that already does what I needed (and also does so much more). However, I still decided to work on 10 Minute Endpoint for the learning experience.

About the Software

Much of the development behind 10 Minute Endpoint was influenced by design restrictions and time limits. I used this project to learn new tools, and I knew I would not be able to add all planned features within the month, so I minimised the goals of the project to remain within scope, and added additional features afterward.

What is 10 Minute Endpoint

10 Minute Endpoint is an open-source service that generates a temporary endpoint for a developer to test and inspect HTTP requests sent to it. This way, they can easily practice making HTTP (or fetch) requests by sending them to this url, or they can use this url in a third party service to easily see the data it sends to their endpoint, which can be useful when developing their APIs that may need certain fields of data.

How it got its name

10 Minute Endpoint (10ME) was originally called Proxyen because of my lack of knowledge on the terminology. I knew of proxies that forwarded requests, and endpoints that managed requests, and mixed those words together.

Throughout further development, I realize that "proxies" was the wrong word to use. Additionally, to prevent overuse of a database (that I don't know how to scale), I decided to follow existing services such as 10 Minute Mail and only provide the endpoint for 10 minutes. After 10 minutes, the endpoint would be deleted, freeing space for other users.

What's its Stack

10ME was developed with the PLEB stack:

• Database/storage with Prisma (MongoDB)
• DevOps/deployed on Linode
• Backend/API with Express (NodeJS)
• Frontend/design using BulmaCSS

How 10 Minute Endpoint works

How it stores data

10 Minute Endpoint uses Prisma and MongoDB as its database.

Why I chose Prisma

I already had experience with applications made using MongoDB and PostgreSQL, but every time, the process of setting up the database, tables, schemas, etc was a tedious task.

Deploying with MongoDB was easier because I could use Mongo Atlas, an online cloud database, whereas in PostgreSQL I had to set up the database in the production server. Previously, I used Heroku to get the PostgreSQL database so they created and managed it for me. But if I had to use a VPS instead of a service helper, I would need to set up the database myself, which would take more time than I would want to spend for the software.

Additionally, I was not sure of what information I would like to store initially, meaning if I had to add more data, I would need to migrate and update table schemas, which would result in more time fighting a database than working on the application. Thus, I chose the easier option that also allows storing dynamic data without migrations: MongoDB.

However, I had only been used to Mongoose for my schemas, and realized I would have to relearn Mongoose for my application's storage purposes. That's when I found Prisma!

Learning Prisma

Prisma allows you to use many databases such as PostgreSQL and MongoDB, and it would manage database migrations, and changing schemas for you. Additionally, it provided a very intuitive API for creating schemas, querying data, creating records, and more. After another day of research and testing, MongoDB still seemed like the simpler database to use, so I chose to use MongoDB with Prisma.

There were some issues using MongoDB locally, since Primsa required a replica set database and I had a standalone, so I used a MongoDB Atlas database instead, and could continue to focus my remaining time on developing the application.

How it generates endpoints

A major design decision for 10ME was whether user accounts were necessary or not. Maybe with user accounts, endpoints could last longer than 10 minutes.

Scrapping the idea of user accounts

However, a user system would require adding authentication, registering, validation, and more which one usually spends a significant amount of time on.

My previous knowledge used sessions logging in (with passport local), and maybe existing authentication forms may be faster (such as OAuth2), but I did not want to add more data to be stored in the database.

Additionally, signing up acts as a barrier to using a service; I just wanted users to visit the page, get their logs, and leave the page when they're done.

Tracking anonymous users

However, I also needed to keep track of anonymous users, so 10ME won't regenerate the endpoint every time the user refreshes the page. For that, I used express session to keep track of user sessions that visit the service.

When users visit for the first time, a user code is created and assigned to them, and stays with them until it expires. When it expires, it is deleted from their session, so when they visit the page again, a new code is generated and assigned to them.

How it deletes endpoints

Every time the server is rebooted, all previous sessions are reset, so even if a user's 10 minutes are not complete, a new session would be created for them if they refresh the page.

This could possibly be prevented by using cookie sessions, but I have to explore that option.

That means it is possible an endpoint can expire, but not be deleted right away. Rather than set a timer to delete each endpoint as they are created, the server has one global timer that deletes all expired endpoints every 10 minutes.

How it logs requests

Similar to how 10 Minute Mail provides a temporary email, 10ME uses the code generated for the user as their endpoint, accepting requests at the "https://10minuteendpoint.net/endpoint/<code>" url. At the "/endpoint" route, requests received are stored with the associated endpoint code, with the request's method, body and query data.

How endpoint logs are displayed

Ideally, when a request is logged, I wanted it to instantly be displayed on the developer dashboard.

One way to do that would be to have an existing websocket connection between the server and developer (client) so the data can be sent to client right away, or server-sent events (SSE) can be pushed from the server to the client on data changes.

However, setting up websockets or SSE turned out time consuming, especially when considering deployment, and having to configure ports and nginx. Thus, the client browser simply polls the server API for new logs. A fetch request to the "https://10minuteendpoint.net/api/logs/<code>" url is sent every second, and all associated logs are returned to the client.

Disadvantage of polling server

After polling the server for logs, it sends all existing logs to the client which then creates the associated html to display it to the developer. Sending all the log data on each request can become resource intensive for the server, potentially causing performance issues.

Slice of Life Optimizations

There are many things I was unable to add due to time, which I would add if I'm able to continue working on 10ME:

Lowering Potential Performance Issues

To minimise the potential performance issues, I can limit each endpoint to store a maximum of 25 logs at once, with new logs replacing older logs in a first in first out flow.

Spam Protection (DOS Prevention)

It is possible that malicious users can send requests requests their endpoints on loop (or even try logging random endpoints). To prevent DOS (Denial of Service) attacks, I can use Umpress in NodeJS on all routes.

Fortunately, Linode automatically detects and mitigates such attacks from happening.

Extending/Renewing Endpoints

10 Minute Mail has the option to extend email addresses to 10 minutes, or renew expired email addresses. To add these features to 10ME, I can create an API that increases the expiry time of the endpoint, but that would only happen if the endpoint is not deleted by the 10 minute loop the server uses.

Currently, once the 10 minutes have passed, the user no longer has access to their logs or the endpoints. Seeing as this is just for testing purposes for the developer, I don't see it as something they can lose data with.

Honest review

In terms of service usage, 10ME successfully solves the original problem I had of testing webhooks and endpoints (although similar services already exist with more features).

In terms of open source software, 10ME is robust and somewhat hard coded, with just enough code to achieve the simple scope of the project. I did follow as much best practices I am aware of, with plans to make the software more flexible in the future.

I also added a readme so other developers can deploy their own instances of 10 Minute Endpoint, and for now it is up to them to extend the functionality for their specific needs.

Conclusion

At the end of development, I learnt of many tools (closed source or bundled with other features) that provided similar solutions like 10ME, such as Webhook Site, Pipedream, Request Catcher, Endpoints, and PTSV2. However, there is still room for the likes of 10 Minute Endpoint.

10 Minute Endpoint logs requests as minimally as possible, does not store user data, deletes endpoint data as quickly as possible, and aims to be used as easily as possible, prioritising simplicity and smooth intuitive usage flow.

Despite the spaghetti code included due to the limited scope and time available, I did learn many new things developing this project, such as database management with Prisma, webhooks, deploying to custom virtual private servers, and how to use the Bulma framework to style your applications.

You can check out the application here and the source code here. I hope 10ME can be useful to you, and I look forward to all your open source projects as well! Thanks for reading.

If you appreciate my work, consider following me on Twitter and supporting me on PayPal or Patreon!

Have you ever needed to integrate software to a server, where you do not have access to the server logs, and no control over what the external API sends to the server? What if you are learning to make HTTP requests and need to confirm that you send the correct data? In both these cases, it could be convenient to be able to inspect the data being sent. That's where 10 Minute Endpoint can help.

10 Minute Endpoint is an open-source service that generates a temporary endpoint for a developer to test and inspect HTTP requests sent to it. This way, they can easily practice making HTTP (or fetch) requests by sending them to this url, or they can use this url in a third party service to easily see the data it sends to their endpoint, which can be useful when developing their APIs that may need certain fields of data.

Why 10 Minute Endpoint?

Existing services store an exhausting amount of information per request, and the records are publicly available. If a third party gets access to the endpoint link, they can view all request logs, which can contain private information of that developer. Additionally, these services allow options to register and log in, storing more data about its users.

Benefits for developers

10 Minute Endpoint addresses all these concerns by:

• Recording as little data as necessary. Only a request's method name, query data, and body data.
• Allowing anonymous users. It does not need to store user information.
• Making all logs private by default. Only the user that received the endpoint link can view the logs sent to that link.
• Deleting data as quickly as possible. The endpoints as well as the associated logs are all deleted after 10 minutes.

Features roadmap

10 Minute Endpoint prioritizes simplicity and minimalism. For that, the feature list is minimal, with enhancements possibly planned for the future:

• [x] v 0.1

  • [x] Set up NodeJS application
  • [x] Add readme and license
  • [x] Create test server
  • [x] Set up managed routes
  • [x] Set up github repo

• [x] v 0.2

  • [x] Track anonymous users by session
  • [x] Generate endpoint for random user
  • [x] Let endpoint expire after 10 minutes
  • [x] Show expiry countdown on client

• [x] v 0.5

  • [x] Set up database
  • [x] Start recording endpoint requests
  • [x] Store endpoint data in database
  • [x] Display endpoint data to client
  • [x] Delete expired data from database

• [x] v 0.7

  • [x] Style frontend client
  • [x] Add favicon and meta tags
  • [x] Add 404 page for all other requests
  • [x] Block bots and web crawlers from using service

• [x] v 1.0

  • [x] Deploy to Linode
  • [x] Configure nginx proxies for public use
  • [x] Enable cors to allow requests to endpoints form anywhere

• [ ] v 1.1
  • [ ] Limit requests logged per endpoint
  • [ ] Allow extending expiry date
  • [ ] Allow renewing expired endpoint
  • [ ] Allow filtering logs by method
  • [ ] Implement custom DDoS protection (currently handled by Linode)
  • [ ] Allow user to send default json responses from requests
  • [ ] Allow user to view request source (IP)

Built With

10ME was developed with the PLEB stack:

• Database/storage with Prisma (MongoDB)
• DevOps/deployed on Linode
• Backend/API with Express (NodeJS)
• Frontend/design using BulmaCSS

Prerequisites

Mongodb

Either install MongoDB locally to your environment, or use one online (through Mongo Atlas for example)

Prisma

Prisma requires a replica set instead of standalone database.

Note - Run prisma generate after installing the packages to generate the MongoDB schemas internally.

Running and Deployment

1. Clone the repo:

   git clone https://github.com/danidre14/10-minute-endpoint-nodejs.git
   

2. Set environment variables for the following (using the .env file, for example):

   • NODE_ENV
   • PORT
   • SESSION_SECRET
   • DATABASE_URL Rename the .env.sample file to .env and use actual credentials obtained in the Prerequisites.

3. Install all dependencies:

   cd /path/to/project
   npm install
   # or yarn install, or other depending on your package manager
   

4. Generate dev dependencies:

   prisma generate
   

5. Run the project:

   npm start
   

   Open a browser and hit http://localhost:5000

Conclusion

10 Minute Endpoint logs requests as minimally as possible, does not store user data, deletes endpoint data as quickly as possible, and aims to be used as easily as possible, prioritizing simplicity and smooth intuitive usage flow.

See the links below to support me or check out the project yourself:

• Github Link: https://github.com/danidre14/10-minute-endpoint-nodejs
• Application Link: https://10minuteendpoint.net
• Twitter: @danidre
• Patreon: Danidre

• Introduction
• Backstory
• Contents
• Game Screen
• Loading Screen
• Mouse Inputs
• Keyboard Inputs
• Main Loop
• Audio Manager
• Texture Manager
• Scripting Flow
• Render Engine
• Data Storage with SharedObjects
• FlevaClips
• Scenes
• Virtual Camera
• Event Handling
• Root Proxy
• Performance Disclaimer
• Flevar's Future
• Conclusion

Introduction

This is a long overdue article, and its creation was encouraged by The Epic Hashnode Writeathon! It is targeted at the Web Apps category, about building browser-based games, and will be an documentation of how I —Danidre, creator of FlevaR— developed FlevaR, a declarative JavaScript game engine for creating 2D browser games and applications.

This article does not aim to be a chronological sequence of the engine's progress, nor does it aim to throw all the engine's code at you. Rather, it aims to be an overview of the current state of the game engine, highlighting the reasons behind the implementations of each component, what inspired me to make each decision, and what I would do differently in the future. I hope you enjoy!

Backstory

At the end of 2020, browsers were ending support for Flash games, meaning the plugins would no longer work. Game developers needed to find other ways to develop and distribute their games. Since its official announcement in 2017, I began learning JavaScript on SoloLearn, and had many prototypes of games and game creators. For some reason, I could only find PhaserJS and PixiJS as alternative browser engines at the time, and the idea of learning something new was daunting, so I decided to create it myself.

One random day in 2020, (and coincidentally a week before Ludum Dare 45 and Geta Game Jam 11), an idea suddenly struck me: What if someone can say "an object exists at this position, and looks this way", and the internal code would handle making it look that way, and place it in the intended destination? I got to coding right away, and a version ready in time for testing out through the game jams. Since then, I've continued to fix bugs, add features, and develop the game engine into its current state (version 2.2.0).

Right now, the engine's main features include textures, audio, collision detection, keyboard and mouse inputs, saving/loading, a virtual camera, reusable scripts, a pre-loader, and its own entity object, called a flevaclip. It was heavily influenced by state hooks inspired by ReactJS, callbacks inspired by ExpressJS and KnexJS, and APIs and abstractions inspired by Flash. Most features are created by abstracting away the complex events and functions offered by modern browsers, and providing them with simple APIs that the developer can use to create whatever game or application they wish to make.

FlevaR's Motto

FlevaR does not focus on being an engine for a specific genre of games, limiting the possibilities of developers. FlevaR simply provides the APIs as much as possible abstracted from the browser. The developer is the one that decides which ones to use for their creations, limited only by their imaginations.

Game Screen

The first thing a player sees on the game's page, is the screen where everything is rendered.

How it works

Internally, the game screen consists of a <canvas> HTML5 element wrapped within a <div> HTML5 element (hence called container). Originally, only a <canvas> element was used. However, this proved difficult when I had to consider fullscreen or resizable applications. Wrapping the <canvas> inside a container that the engine can control would allow direct control of the position of the canvas based on absolute and relative positions in the browser:

const canvasdiv = document.createElement("div");
canvasdiv.setAttribute("style", `border-style: solid; border-width: 2px; width: ${_width}px; height: ${_height}px; position: relative;`);
canvasdiv.style.overflow = "hidden";
canvasdiv.style.outline = "none";
canvasdiv.style.border = "none";
canvasdiv.tabIndex = "0";

const canvas = helperFunction.createCanvas(_width, _height);
canvas.setAttribute("style", "position: absolute;");
const globalCtx = canvas.getContext("2d");
globalCtx.imageSmoothingEnabled = false;

canvasdiv.appendChild(canvas);
browserdiv.appendChild(canvasdiv);

It also allowed for internal calculations to handle the scaling and position of the canvas (such that it can properly be centered in screen sizes of different aspect ratios).

How to use it

When the developer initializes the engine, they must provide a default element that the engine will use, as well as options such as the dimensions of the screen, or fps of the application:

index.html

<body>
    <!-- container for our application -->
    <div id="flevaRContainer"></div>
</body>

main.js

const flevaRContainerElement = document.getElementById("flevaRContainer");
FlevaR(flevaRContainerElement, { _width: 600, _height: 500, fps: 30 });

Then, a screen of appropriate dimensions will be created and used to render all scenes and flevaclips. The resulting HTML would look something like the following:

index.html

<body>
    <!-- container for our application -->
    <div id="flevaRContainer">
        <div style="border: none; width: 600px; height: 500px; position: relative; overflow: hidden; outline: none; cursor: default;" tabindex="0">
            <canvas width="600" height="500" style="position: absolute; left: 0px; top: 0px;"></canvas>
        </div>
    </div>
</body>

The tabindex allowed the canvas to receive focus for mouse and key inputs. The left and top are adjusted internally to position the canvas in the middle of the screen.

How I would improve it

Screen occupancy

Currently, the canvas only stretches to fit the provided dimensions, and multiple aspect ratios are not supported. In the future I plan on modifying the canvas (and render engine) to resize to fill the spaces shown by the black borders. This can be useful especially with mobile devices and landscape/portrait orientations.

Multiple wrapped HTML elements

Since the canvas is already wrapped in a div, if I needed to add extra elements (such as error logs when an application crashes), I could easily include it in the div without having to worry about whether the developer's website's HTML will be structured in a format to accept it.

Multiple canvases

I plan on extending the engine to allow developing mobile/touchscreen games. A second canvas can be useful for displaying virtual joysticks that can be configured by the developer, and used easily by the player.

back to contents

Loading Screen

Depending on the configurations of the game, the built-in loader is shown, and all the assets (textures and audio) is loaded in the browser:

How it works

Internally, all assets passed to the engine are initially queued, and one by one loaded as JavaScript Promises, which are resolved when the onload event for the image (or onloadeddata for audio) is called. The length of the loading bar is calculated then by the current number of assets loaded divided by the initial length of the queue.

// ...other loading code
for (const asset of queueList) {
    const source = asset.source;
    try {
        await source.loadSource();
    } catch (e) {
        console.error("Error while loading assets: " + e);
    }
    loadCounter++;
    renderLoadScreen(); // updates load bar
}

When each asset is loaded, the current number increases and the loading bar lengthens. When all assets have been loaded, an option opens to allow the player to click anywhere or press a button to start the game.

Internally, I add temporary mousedown and keydown event listeners that start the main loop of the engine and immediately remove the temporary event listeners:

// ...other loading code
const finishLoad = () => {
    queueList.length = 0;
    window.removeEventListener("resize", renderLoadScreen, false);
    _screen.div.removeEventListener("mousedown", finishLoad, true);
    _screen.div.removeEventListener("keydown", finishLoad, true);
}
_screen.div.addEventListener("mousedown", finishLoad, true);
_screen.div.addEventListener("keydown", finishLoad, true);

How to use it

Within the main load function of the FlevaR application, part of the API provided allows for developers to load their textures and sounds, using relative paths of the assets:

sample directory

-- assets (folder)
   -- nice-image.png
   -- cool-sound.mp3
-- index.html
-- flevar.js
-- main.js

main.js

// ...other code
FlevaR(flevaRContainerElement, { _width: 600, _height: 500, fps: 30 }, function onload(core) {
    /* Within engine's onload */
    const { createSound, createGraphic } = core;
    createSound("mySound", { _name: "cool-sound", _type: "mp3", _path: "assets" });
    createGraphic("myGraphic", { _name: "nice-image", _type: "png", _path: "assets" });
});

These calls send the assets to the queue which is handled internally as described above.

If the engine had already been loaded by the time the APIs were called, the assets are loaded in the background. Resources that depend on the assets would default to their placeholder assets until they are loaded.

How I would improve it

Parallel Loading

Currently, assets are loaded sequentially, and each asset waits until the other is complete first before loading the next:

const queueList = [asset1, asset2, asset3];
for(const asset of queueList) {
    // await waits for each promise to be resolved, which occurs when each asset is loaded
    await asset.source.loadSource();
}
/*
Sample estimated duration:
========O                   asset1
===========O                asset2
=====O                      asset3
========================O   total
*/

I recently learnt more capabilities of Promises; you can fire multiple promises and await them all. Rather than one after the other, all assets would begin to load and resolve at shorter times depending on size:

// ...pseudocode
const queueList = [asset1, asset2, asset3];
const promiseList = [];
for(const asset of queueList) {
    promiseList.push(asset.source.loadSource());
}
// wait for the Promise.all to be resolved
await Promise.all(promiseList);
/*
Sample estimated duration:
========O      asset1
===========O   asset2
=====O         asset3
===========O   total
*/

Priority (Smart) Loading

Right now, all assets are tried and loaded. However, not all assets are needed right away (for example, boss music would not need to be loaded as the game loads). A hope is for the engine to determine which assets need immediate loading and which assets can load in the background in whatever free time is available. This can lower the amount of assets loading at engine startup, and reduce loading duration.

I have no knowledge on any methods possible to implement this just yet.

back to contents

Mouse Inputs

Right after the engine loads, temporary event listeners allow the player to play the game (start the engine). Similar to Keyboard Inputs, a Mouse module is provided by the core of the engine with APIs for developers to handle mouse movement and clicks from the player.

Some Supported APIs

• Mouse.LEFT
• Mouse.MIDDLE
• Mouse.RIGHT
• Mouse.isDown()
• Mouse.isUp()
• Mouse.isPressed()
• Mouse.isReleased()

The x and y coordinates of the mouse pointer is also provided by the engine, although through a different object: _root. The x position is obtained from _root._xmouse, and the y position is obtained from _root._ymouse.

What influenced it

The mouse APIs were heavily influenced by the ActionScript 2.0 APIs provided by Adobe Flash, although due to the architecture of the main loop, I added additional functions such as isPressed and isReleased.

How it works

Conveniently, all major browsers provide mouse event listeners that can be used to get the position of the mouse relative to an HTML5 element, as well as determine when mouse actions —such as clicks and scrolls— are fired.

Mouse Positions

The convention for many games have coordinates relative to the screen with the top left of the canvas being position [0, 0], and the bottom right of the canvas being positions equal to the width and height of the canvas. Rather than leave the developer to figure out the mouse positions each frame, FlevaR abstracts this layer away and provides a simpler API for the developer to use. This helps keep the mouse coordinates consistent regardless of how small or large the screen is after initialization.

The engine adds a "mousemove" event listener to the container on engine load, and from there handles the event, computes the cursor positions based on the location of the cursor in the browser, relative to the top left corner of the container. That value is then offset by the relative position of the canvas wrapped inside the container, and scaled depending on the aspect ratio of the screen, and stored as x and y positions.

_screen.div.addEventListener("mousemove", setMousePosition, false);
// ...other code
function setMousePosition(_event) {
    const canvas = _screen.canvas;
    const rect = canvas.getBoundingClientRect(),
        scaleX = canvas.width / rect.width,
        scaleY = canvas.height / rect.height;

    const mouseX = Math.ceil((_event.clientX - rect.left) * scaleX / _screen.xScale);
    const mouseY = Math.ceil((_event.clientY - rect.top) * scaleY / _screen.yScale);

    Mouse._xmouse = numberUtils.clamp(mouseX, 0, stage._width);
    Mouse._ymouse = numberUtils.clamp(mouseY, 0, stage._height);
}

Other indirect events such as "mousedown" (when the mouse pointer is pressed) or "fullscreenchange" (when the application enters or exits fullscreen) also call the setMousePosition function to keep the internal stored mouse positions up-to-date with changes in the application.

The Mouse._xmouse and Mouse._ymouse properties are later exposed from the internals of the engine to the developer through the root proxy.

Mouse Functions

The engine also adds "mousedown", "mouseup", and "mouseleave" events to capture those actions and abstract it into easy APIs the developer can use.

_screen.div.addEventListener("mousedown", setMouseDown, false);
_screen.div.addEventListener("mouseup", setMouseUp, false);
_screen.div.addEventListener("mouseleave", setMouseLeave, false);

Providing isDown and isUp functions was easy: simply store the mouse button being held down, and the function will return a boolean if that button was stored for isDown, and the opposite for isUp.

However, it is not so simple for the isPressed and isReleased functions. Rather than try to explain in theory, here is a simplified process of how each action is handled:

// only checking left mouse button for simplicity
function setMouseDown(_event) {
    setMousePosition(_event);
    // left mouse button is code 0
    if (_event.button === 0) {
        // if the key in the list does not exist,
        // set it to true (helpful for isDown)
        if (Mouse._mouseList._left === undefined)
            Mouse._mouseList._left = true;

        // if the key in the pressed list does not exist,
        // trigger the mouse pressed function (helpful for isPressed)
        if (Mouse._mousePressed._left === undefined)
            this.setMousePressed(_event);
    }
}

function setMousePressed(_event) {
    if (_event.button === 0) {
        // set pressed to true
        Mouse._mousePressed._left = true;
        // ...other code
    }
}

function setMouseUp(_event) {
    if (_event.button === 0) {
        // if the key is in the list, remove it from the list (helpful for isUp)
        if (Mouse._left) delete Mouse._left;

        // if the key is in the pressed list
        if (Mouse._mousePressed._left !== undefined) {
            // is key in released list does not exist,
            // trigger the mouse released function (helpful for isReleased)
            if (Mouse._mouseReleased._left === undefined)
                this.setMouseReleased(_event);

            // remove key from pressed list
            delete Mouse._mousePressed._left;
        }
    }
}

function setMouseReleased(_event) {
    if (_event.button === 0) {
        // set released to true
        Mouse._mouseReleased._left = true;
        // ...other code
    }
}

Internally, three states are used: mouseList, mousePressed, and mouseReleased, and rather than just checking whether the specific button in each state is true or false, three states are used: true, false, undefined. The mouseList is used to add or remove the button from the list, to easily check whether the isDown function works. The engine will simply check whether that button exists in the state (isDown returns true) or not (isDown returns false). Inversely, isUp will check whether the button exists in the state (isUp is false) or not (isUp is true).

isUp actually calls isDown internally and returns the opposite of that result.

const isUp = function (_key) {
    return !isDown(_key);
}

For isPressed to work, it is not enough to check whether the button exists in the mousePressed list. That is because if you hold down the button, you want the isPressed to be true only once until the key is first released, then true only once again the second time it is pressed.

On every loop*, the engine first captures all mousepresses from the event listeners and abstracts them into their appropriate states, runs the tick methods for all scenes and objects which executes the scripts that check for isPressed, and then "clears" the states accordingly. Internally, this simply changes all buttons in the pressed state to false, rather than delete them.

*This is a simplified section of what the loop does.

Therefore, if a button is pressed, it is added to the mousePressed state as true on the first state, and then false on every subsequent tick that the key is being held down, until it is removed from the state when the button is released.

for (const _key of Object.keys(_mousePressed)) {
    if (_mousePressed[_key] === true) _mousePressed[_key] = false;
}

The isPressed function only checks if the button is true in the mousePressed state, and as such is only true the first time, each time the button is pressed.

Similarly, isReleased checks if the button exists in the mouseReleased state, which is added once when the button is released, stored in the state, handled once in the tick, and subsequently removed from the list right after when the list is cleared.

for (const _key of Object.keys(_mouseReleased)) {
    delete _mouseReleased[_key];
}

Mouse Codes

The Mouse Module provides pre-computed codes for the "left" (Mouse.LEFT, which is code 0), "middle" (Mouse.MIDDLE, which is 1), and "right" (Mouse.RIGHT, which is 2) mouse buttons.

How to use it

Within any script, the developer can call the APIs in their scripts to detect when mouse activity occurs, as well as which mouse button triggered the activity:

const x = _root._xmouse;
const y = _root._ymouse;

if(Mouse.isDown(Mouse.RIGHT)) {
    this._text = "Right button is down";
} else {
    this._text = "Right button is not down";
}
if(Mouse.isPressed("left")) {
    if(this._fontColor === "black")
        this._fontColor = "white";
    else
        this._fontColor = "black";
}

How I would improve it

Cleaner Mouse API

Right now, mouse positions are obtained using the root proxy, and mouse functions are called using the Mouse module. This was done mainly to copy AS2 APIs provided by Adobe Flash. In hindsight, I see no need for separate objects having mouse-related values. Having the mouse positions simply be provided to the developer as Mouse._x and Mouse._y would be better both for simplicity, as well as speed.

The root proxy is slow. Check that section to find out why.

Touch Support

Inspired by Adobe Flash's AS2 API, I modelled as much as possible behind it; there was no native touchscreen support, so I had not even considered that in the engine. However, many game engines have support for it, and many people play mobile browser games. In the future, along with virtual joysticks, I want to add a Touch module with similar APIs to the Mouse and Key modules (with obvious differences to support all 10 touch points). To achieve this, I plan to use touch events provided by modern browsers, and abstract accordingly.

General Pointer Support

Recent browsers have general support for Pointer Events, which include mouse, pen/stylus or touch. Abstracting and providing this API as a Pointer module can continue to help developers use it for anything, such as a drawing application created in FlevaR that uses a stylus. FlevaR provides; Developer decides.

back to contents

Keyboard Inputs

Right after the engine loads, temporary event listeners allow the player to play the game (start the engine). Similar to Mouse Inputs, a Key module is provided by the core of the engine with APIs for developers to handle keyboard actions from the player.

Some Supported APIs

• Key.UP
• Key.A
• Key.ENTER
• Key.isDown()
• Key.isUp()
• Key.isPressed()
• Key.isReleased()

What influenced it

The keyboard APIs were heavily influenced by the ActionScript 2.0 APIs provided by Adobe Flash; although due to the architecture of the main loop, I added additional functions such as isPressed and isReleased.

How it works

Conveniently, all major browsers provide keyboard event listeners that can be used to determine when keyboard actions are fired. The engine uses "keydown" and "keyup" events to capture these actions and abstract it into easy APIs the developer can use.

_screen.div.addEventListener("keydown", setKeyDown, true);
_screen.div.addEventListener("keyup", setKeyUp, false);

There are many ways to determine the specific key fired in the browser event listeners. For example, if the "A" key is pressed, that key can be obtained with one of the following:

// assuming the "A" key is pressed
document.addEventListener("keydown", function(event) {
    let {which, keyCode, code, key} = event;
    console.log([which, keyCode, code, key]);
    // outputs [65, 65, "KeyA", "a"]

In keeping with Flash's AS2 API, I wanted to allow developers to input keyCode numbers (65) or pre-computed properties (Key.LEFT, which is also keyCode 35); but I also wanted more flexibility, such as key strings ("a", or "enter") and more pre-computed properties not included in Flash AS2 (Key.A, or Key.ONE). To achieve this, both the key codes and key names are stored internally:

function setKeyDown(event) {
    const keyCode = "code_" + event.keyCode;
    const keyName = "name_" + event.key.toLowerCase();
    if (Key._keysList[keyCode] === undefined) Key._keysList[keyCode] = true;
    if (Key._keysList[keyName] === undefined) Key._keysList[keyName] = true;
    // ...other code

The values prepended by "code_" and "name_" help distinguish between the types. If the "A" key was pressed, it will be stored both as "code_65" and "name_a". Thus, when checking for an existing key (comparing in the isDown for example), the appropriate state will be checked:

Key.isDown = function (_key) {
    if (typeof _key === "string") {
        _key = _key.toLowerCase();
        if (KeyMap[_key]) _key = KeyMap[_key];
    }

    const keyDown = Key._keysList["code_" + _key] ||
        Key._keysList["name_" + _key] || false;
    return keyDown === true;
}

Internally, the KeyMap stores all irregular key names and their corresponding key codes ("alt" -> 18; "zero" -> 48).

The function accepts the value passed and:

1. If it is a string, use the lowercase of that string and map it to the corresponding key code.
   Example: Calling Key.isDown("FIVE") will internally look for the key code 53, etc.

2. Compare whether that _key value —prepended with "code_" or "name_"— is in the keylist state.
   Example: Calling Key.isDown(65) will compare with both "code_65" and "name_65", which will match with the first option if that key is in the list.
   Calling Key.isDown("B") will compare with both "code_b" and "name_b", which will match with the second option if that key is in the list.

3. Return the result.

Evidently, options such as "name_65" and "code_b" will never exist, but the double setting allows for the most flexibility.

In modern browsers, both keyCode and which properties are considered deprecated. However, they were still implemented in keeping with Flash's AS2 API —as well as to, once again, provide key flexibility— with an encouragement to use the modern suggested key property.

Keyboard Functions

Similar to the Mouse Module, FlevaR's Key isDown, isUp, isPressed and isReleased functions are implemented with the three states and managed with the loop system.

How to use it

Within any script, the developer can call the APIs in their scripts to detect when keyboard activity occurs, as well as which key triggered the activity:

/* Within flevaclip's onload */
const speed = 5;
if(Key.isDown(Key.A)) {
    this._x -= speed;
} else if(Key.isDown("d")) {
    this._x += speed;
}
if(Key.isDown(87)) { // w
    this._y -= speed;
} else if(Key.isDown("S")) {
    this._y += speed;
}
if(Key.isDown(Key.Q)) {
    this._rotation -= speed;
} else if(Key.isDown(69)) { // e
    this._rotation += speed;
}

How I would improve it

Gamepad Support

Inspired by Adobe Flash's AS2 API, I modelled as much as possible behind it; I was not aware of any native gamepad support, so I had not even considered that in the engine. However, many game engines have support for it on browsers, and it is also something I personally want to provide in the engine. To achieve this, I plan to use gamepad APIs provided by modern browsers, and abstract accordingly.

back to contents

Main Loop

After the engine has been loaded the main loop begins. For FlevaR, this loop is basically a function that is called repeatedly for the duration of the game, which gives the player the illusion of an animation and game. In this loop, all scripts are executed and objects are rendered. However, many more operations occur within each loop, and with the help of events captured by the browser, the general internal execution system of the engine is as follows:

The Execution System

Check for Background Assets

The main assets loaded before the game begins are created within the engine's initialization script. Therefore, it is possible that the developer would have code stored elsewhere to load assets at other points in the running of the game (after it has loaded). The engine simply checks the queue for assets and sends them to be loaded in the background (if they aren't already in the process of being loaded)

Run Scripts (Tick Method)

Scripts are created and attached to objects as callbacks. The tick method crawls through the engine core, current scene, and active flevaclips and executes the scripts the developer would have written. The order of script execution depends on the order the object was added to the screen.

Clear Input States

After the scripts are executed, the input states would be refreshed to be recaptured by Browser Event Listeners and abstracted again. This helps methods such as isPressed and isReleased on the Mouse and Key modules work.

Render Objects (Render Method)

Although each object has its own tick and render methods, they are called separately. Unlike the tick method, the order of rendering is not only dependent on the order the object was added to the screen. Flevaclips can have varying depths, and are added to a list based on their depth value. It is very possible that the first flevaclip has a higher depth than the last flevaclip, and the 3rd flevaclip has a lower depth than the 8th flevaclip, for example. When rendering, the list is traversed in ascending order and flevaclip rendered; thus, flevaclips with a higher depth would be rendered after a flevaclip with a lower depth, and as such would be seen on top.

The depth sequence of the above flevaclips, from lowest to highest, would be: 1, 2, 3 (left); and 1, 3, 2 (right).

Check for Concurrent Assets

Rather than waiting for extra assets to be loaded in the background, some developers may want to pause the game until they are loaded. At this stage, any assets added with the concurrent option would then be loaded.

Some browsers never load assets if the page is not currently selected. Thus, this function is only called if the page is focused.

Resolve Queued Functions

Some engine functions must be executed asychronously, even if the developer does not explicitly do so. Additionally, other functions must be queued until the player interacts with the application (such as playing audio). Depending on the state of the engine at that point of method call, the functions may be executed right away or queued and executed at a later time.

That "later time" is at the end of the loop cycle, after scripts are ran, assets and states are managed, and objects are rendered.

How it works

For FlevaR, I wanted a reliable and consistent loop.

setTimeout and setInterval

I first considered using setTimeout and setInterval, since they can call functions repeatedly with a consistent time delay.

setTimeout and setInterval Limitation

However, I noticed that the time delay was only consistent while the page was focused; anytime you left the page, each interval would take longer to be called instead of the set time.

With an intended fps value of 30, the expected average frame delay is 33ms (1000 / 30); however, it jumps closer 1 second when the game tab loses focus. Check here for an interactive test.

This reduced the reliability of setInterval's consistency, since I wanted it to execute at the desired frame rate whether the tab was focused or not.

requestAnimationFrame

The second thing I learned was the browser's requestAnimationFrame. It was created for browser animations and thus was better suited for animation loops in games.

requestAnimationFrame Limitation

Unfortunately, this method was also unreliable in moments where the tab was hidden.

Custom Function

After more research, I briefly learnt about Web Workers, which run scripts in the background and sends responses to the foreground. Fortunately, setTimeouts work consistently in web workers, even when the tab isn't focused. Thus, FlevaR creates a background timer (web worker) that sends a message to the foreground in consistent reliable intervals (calculated based on the fps) that calls the main loop's function. When the loop function is complete, a message is sent to the background timer which will calculate the time passed and determine how long it should take before sending another message to the foreground.

Assuming an fps of 25, frames should be called every 40ms from the time the loop starts: 40, 80, 120, etc

If the first frame called at 40ms takes 7ms, the next time out will be called to accommodate for the time difference, keeping the delay between each call as consistent as possible.

0ms:
    Loop begins
    Background sets timeout for 40ms
40ms:
    Timer sends message to foreground to run loop
    Loop function takes 7ms to complete
47ms:
    Loop sends message to background that loop completed
    Background sets timeout for 33ms (80ms - 47ms)
80ms:
    Timer sends message to foreground to run loop
    ...

Due to how browsers work, the delay is never 100% accurate, but with this method it was always close and accurate enough.

How to use it

The developer does not actually worry about the main loop. It is handled internally from the moment the game loads. However, considering that developers may also want custom timeouts that are reliable even when other tabs are focused, FlevaR provided createTimeout, removeTimeout, createLoop, and deleteLoop functions with similar APIs to the browser equivalents (setTimeout, clearTimeout, setInterval, clearInterval). The benefit to using the FlevaR provided functions was that they were called with consistent intervals, regardless of whether the browser was focused or not.

// create plain "Hello world!" function
const myFunction = function() {
  trace("Hello world!");
}

// call function every 3 seconds
createLoop(myFunction, 3000);

/* Output expected */
// > "Hello world!"
// > "Hello world!"
// > "Hello world!"
// > "Hello world!"
// ...

How I would improve it

Fixed Timestep

Although reliable, the loop struggled to keep an FPS of 120 when that value was set. I'm uncertain whether it is due to the high delay of a web worker communicating with the foreground, but that could be a bottleneck when you want each frame to be called every 8.33ms (for 120 fps). The best option to take would be to use requestAnimationFrame, since it was created for such consistent animations. However, in cases where I want a game to be up to date (with all scripts running consistently), this option fails when another tab is focused.

Gradually, through- many- gameloop- articles, I believe the best thing to do would be to call the loop as much as possible. In it, the tick methods and scripts will be called zero, one, or multiple times, depending on how long ago the last frame was called, compared to how often each frame should be called.

const fps = 30;
const step = 1/fps;

let now;
let dt   = 0;
let last = timestamp();

function frame() {
  now = timestamp();
  dt = dt + Math.min(1, (now - last) / 1000);
  while(dt > step) {
    dt = dt - step;
    tick(step);
  }
  render(dt);
  last = now;
  requestAnimationFrame(frame);
}

requestAnimationFrame(frame);

Code used from this article.

That way, even if the tab loses focus, if the last frame was called 1000ms ago when 30 frames were supposed to be called during that second, the tick method would be called 30 times within the while loop, and then the render method would be called only once after that, to reflect the latest change. It will make up for the lack of interval consistency by simulating the frames as much as possible to get back on track.

Fixed Timestep Advantage

With the fixed timestep, a delta can be provided from the engine to the developer that would be used to develop deterministic games. The delta would basically be the same each frame; the engine will make the necessary steps to keep everything else consistent even when delays occur.

Fixed Timestep Disadvantage

The only possible downside I can see with this option is the delay in an online multiplayer game. It is important to get updates from the server multiple times every frame and process them accordingly; even a drop in frame can have visible effects on the player when they leave and return to the game tab. They may have to queue updates from the server and lerp differences to maintain visual consistency when the player leaves and returns to the game tab. However, I leave that up to the developer to implement.

I still have more to consider before I determine a better loop to use that is both fast and reliable, so more research is necessary here.

back to contents

Audio Manager

Depending on how the developer created the game, music is played at the menu screen, or sound effects are triggered when buttons are hovered or pressed. FlevaR's audio manager abstracts the way browsers load audio, and provides a simple API the developer can use for their games.

What influenced it

The audio APIs were created and modified from previous versions of games I worked on before the FlevaR game engine.

How it works

When the developer calls the functions to create sounds in the game, Audio objects are created internally. By default, the engine assumes the audio files are stored in an asset folder in the working directory of the application. However, developers can also provide parameters to change the path, name, and extension of the audio file.

When the create sound functions are called, the sources of the audio files are queued and loaded sequentially (while the game is loaded) or in the background (when the game is being played). Internally, FlevaR uses the Audio object's onloadeddata event to determine when enough of the file has been loaded and can be played.

Some browsers do not fire the onloadeddata event in time for the asset, which caused errors of applications freezing on load because the event was never fired. As a result, FlevaR checks onloadeddata, onloadedmetadata, oncanplay, and oncanplaythrough events; The asset will be considered loaded based on whichever event is fired first.

When the asset is loaded, APIs are made available to interact with the sound file (play, clone, stop, and more). Properties are also provided for the developer's convenience (volume, loop, and more).

How to use it

The default syntax to create a sound is createSound(name, config). The developer first creates a sound clip, providing a name, and if necessary, the sound's path in the working directory of the application:

Example

Create a sound clip, using an mp3 audio clip called mySound from an assets folder in the same directory as the html file:

/* Within engine's onload */

createSound("mySound", { _name: "mySound", _type: "mp3", _path: "assets" }); // <- either 

createSound("mySound"); // <- or

Note: In this scenario, the config object can be omitted, because if none are provided, by default, type = "mp3", path="assets", and the name would be what was provided by the developer.

Create a sound clip, using a wav audio clip called meow_sfx from an audios folder in the same directory as the html file:

/* Within engine's onload */

createSound("mySound", { _name: "meow_sfx", _type: "wav", _path: "audios" });

Create a sound clip, using a free audio file from another website/url:

/* Within engine's onload */

createSound("mySound", { _src: "https://a.fakeaudiourl.com/rQIk1oe.mp3" });

To use the sound clip, the developer can use the APIs provided by the Sound Module:

/* Within scene's async onload */

const mySound = Sound("mySound");

await mySound.play(); // <- either

await Sound("mySound").play(); // <- or

Check FlevaR's docs for more uses of the Sound Module

How I would improve it

Deferred Playback

When the developer calls mySound.play(), the engine tries to play the audio right away. Some browsers prevent this from happening if the tab has not been interacted with by the user, which causes the engine to return an error and crash in these instances. An internal check can be created to determine whether the player interacts with the application or not. If they have not; the audio methods can be queued, so that only when the player clicks into the screen, the queues will be resolved, the audio methods will be executed, and the browsers will not complain or crash the engine.

Spacial Audio

Rather than an improvement, a feature I considered adding was audio with a position in the application. The volume would increase or decrease based on the distance the audioclip was from a flevaclip or other object in game.

However, I realized that this functionality can be easily implemented in a flevaclip instead. Due to the nature of flevaclips being reusable components, I scrapped the implementation to allow the developer that option, as well as keep the engine as minimal as possible.

I know I say minimal, but the engine has about 8000 single lines of code.

back to contents

Texture Manager

Similar to the Audio Manager, images are handled by FlevaR rather than the developer worrying about loading and managing them. In FlevaR, they are referred to as Graphic types, and all APIs used to interact with them follow a similar name.

What influenced it

The texture APIs were created and modified from previous versions of games I worked on before the FlevaR game engine.

How it works

When the developer calls the functions to create graphics in the game, Image objects are created internally. By default, the engine assumes the image files are stored in an asset folder in the working directory of the application. However, developers can also provide parameters to change tha path, name, and extensions of the image file.

When the create graphic functions are called, the sources of the image files are queued and loaded sequentially (while the game is loaded) or in the background (when the game is being played). Internally, FlevaR uses the Image object's onload event to determine when enough of the file has been loaded and can be displayed.

Deeper dive

To get a better understanding of how the graphics work (and are used in the engine), here is a sample snippet of the actual Graphic object in FlevaR:

When the developer "creates" a Graphic, they can state the location and extension of the image with the _path, _name, and _type properties, or _src entirely.

_src can also be used as a URL for images from other websites.

Initially, the Image object is created but the source is not immediately set. Instead, it is added to FlevaR's internal library of assets. A loadSource asynchronous function is created that sets the source of the image file which triggers the browser loading it. Upon engine load (or during synchronous or background asset checks), the loadSource promise is called for each asset.

You may notice additional properties such as pixelMap. This property is a map of the individual pixels in the Graphic, which is cached internally for pixel-based collision detection.

When the asset is loaded, resources that depend on them will be able to use them; until then, resources that rely on these assets (flevaclips) display a default placeholder provided by the engine:

How to use it

The default syntax to create a graphic is createGraphic(name, config). The developer first creates a graphic, providing a name, and if necessary, the graphic's path in the working directory of the application:

Example

Create a graphic, using a png image called myGraphic from an assets folder in the same directory as the html file:

/* Within engine's onload */

createGraphic("myGraphic", { _name: "myGraphic", _type: "png", _path: "assets" }); // <- either 

createGraphic("myGraphic"); // <- or

Note: In this scenario, the config object can be omitted, because if none are provided, by default, type = "png", path="assets", and the name would be what was provided by the developer.

Create a graphic, using a jpg image called kitten from an images folder in the same directory as the html file:

/* Within engine's onload */

createGraphic("myGraphic", { _name: "kitten", _type: "jpg", _path: "images" });

Create a graphic, using a free image from another website/url:

/* Within engine's onload */

createGraphic("myGraphic", { _src: "https://i.imgur.com/rQIk1oe.png" });

How I would improve it

Image Atlas

Currently, a new object is stored in memory for each image the game has.

One option I've considered is to create a large canvas that stores multiple images on it.

I have not checked whether one large file is better than multiple small files, but many engines go the route of storing multiple assets on one file.

The idea would be for FlevaR draw each image onto the canvas when they have loaded, and store those dimensions as occupied. That way, when a new image is created by the developer, it will be added to the canvas at an appropriate available space, or a new large canvas would be created if it can no longer fit.

back to contents

Scripting Flow

An average game runs at 60 frames per second. That means scripts are executed 60 times per second, and then rendered just as fast to give the illusion and enjoyment of movement and gaming. Some scripts are called each frame, while others are only called based on a trigger, such as an object being loaded or unloaded. FlevaR provides a flow that developers can use to both maintain the simplicity of programming, and the flexibility of the declarative language involved through its APIs.

What influenced it

The architecture behind the way scripts work in FlevaR is inspired by ExpressJS and KnexJS. I do not recall what specifically inspired me, but I believe it was related to how function callbacks are handled. With ExpressJS, you define middlewares by passing functions, which are then run based on that request. Similarly, you pass functions as the parameters for other methods in FlevaR, that are then executed on a needed basis:

flevaclip.addScript(function myScript(self) {
    trace("Hello World");
});

The myScript function will be stored as a callback and executed on every frame.

How it works

The main components in FlevaR are the engine core, the scenes, and the flevaclips. When the engine loads, a method is called to use a scene previously created. When that scene is being loaded, all flevaclips in that scene are also loaded. Afterward, the scripts in each scene/flevaclip are executed each frame, until another scene is loaded (or a flevaclip is removed). Before the other scene is loaded, the current scene first unloads (calling its unload script if it exists), and all current flevaclips are also unloaded. Then the next scene and its flevaclips are loaded.

General Application Lifecycle

// start
- Engine load
- Engine tick

// choose scene
- Scene load
- Flevaclip load
- Scene tick
- Flevaclip tick
- Scene tick
- Flevaclip tick
- Scene tick
- Flevaclip tick
...

// next scene
- Flevaclip unload
- Scene unload
- New scene load
- New flevaclips load
- Scene tick
- Flevaclip tick
- Scene tick
- Flevaclip tick
...

General Scripting Syntax

All scripts in the engine are passed as parameters for the engine to use as callbacks. Whenever they are executed, the engine passes the object specifically needed in that function.

For example:

• when the engine loads, the engine core is provided in the engine's onload function for the developer to create the game using core specific methods.
• when the scene loads, the scene object is provided in the scene's onload function that the developer can use to add flevaclips or execute scene specific methods.
• when a flevaclip loads, the flevaclip object is provided in the flevaclip's onload function that the developer can use to manipulate its properties and execute methods on that flevaclip.
• when a flevaclip's script is executed, the flevaclip object is provided in the callback function that the developer can use to manipulate its properties each frame.

Core Syntax

When the developer creates the engine, they define the configurations as well as the onload method of the engine: FlevaR(config, onload).

FlevaR passes the core object to this onload method, which is used to develop all the scenes, add all the assets, and create all the necessary scripts for the entire game.

Scenes Syntax

When creating a scene, the general format is to include a name parameter (string), and an onload parameter (function): createScene(name, onload).

Within the onload function, the scene object will be passed, which can be used to access all the methods provided by a Scene object. This load function is only executed once each time the scene loads. In this function, the developer can define all other flevaclips they want in the scene. If the developer wants scripts to run each frame, they add those scripts inside an addScript() method provided by the scene object.

Scene scripts created to run every frame are also passed the scene object by the engine, so more methods can be called each frame.

Each onload function can optionally return a function that FlevaR will use for the onunload methods. When the scene is created, the onload functions are stored internally in the scene object's private inits (initializations) array. When the scene loads, the inits array is iterated and the functions are executed:

// scene's private load method
function load() {
    for(const init of inits) {
        const fini = init(scene);
        if(helperUtils.isFunction(fini) {
            finis.push(fini);
        }
    }
}

If a function was returned on each execution, they are stored in the scene object's private finis (finalizations) array, similar to the syntax for code executed when a component is unmounted in ReactJS.

The scene.addScript(func) method adds those functions to the scene object's private scripts array. These functions are executed every frame:

// scene's private tick method
function tick() {
    for(const script of scripts) {
        script(scene)
    }
}

The script(scene) executes the callback script and passes the scene object that the developer needs to access the scene's properties and methods.

When another scene has to be loaded, the current scene first iterates through its finis array to call the unload methods:

// scene's private unload method
function unload() {
    for(const fini of finis) {
        fini(scene);
    }
}

Similar to the Flevaclips Syntax, multiple onload functions can be created, all with their optional returned onunload functions.

Flevaclips Syntax

Just like the Scenes Syntax, flevaclips are created with a parameter for their onload function: createPrefab(name, props, onload).

Inside this function, the engine passes the flevaclip object that can be used to call all flevaclip methods. An optional return function is also available to be called when the user wants to perform additional functions when the flevaclip has been unloaded.

Multiple Onload Parameters

The first main goal of FlevaR was to define flevaclips once and use them as templates for future flevaclips. That way, all onload methods (as well as scripts and unload methods) from previous flevaclip templates would be called on subsequent flevaclips that were created from those templates. To get all these onload functions on the same flevaclip, FlevaR adds them to an inits array. For design flexibility, FlevaR also accepts multiple onload functions when adding the flevaclip, as subsequent parameters: createPrefab(name, props, onload1, onload2, onload3, ...).

Generally, game engines have one onload function for their entities, so I considered using a simple syntax such as createPrefab(name, props, onload, onunload). However, due to the goal of reusing flevaclips as templates, I chose the route of allowing multiple onload functions, each with the option of returning a function that can be used as an onunload.

How it is used

The general flow of a flevaclip or scene with the flexibility of multiple callbacks is up to the needs of the developer.

Suppose the developer wanted a scene that does the following:

• Outputs "Hello scene" when loaded.
• Adds a flevaclip to the scene when loaded.
• Outputs "Running scene" every frame.
• Outputs "Goodbye scene" when unloaded.

The related code for the above requirements would be the following:

/* Within engine's onload */
createScene("myScene", function onload(scene) {
    // Outputs "Hello scene" when loaded.
    trace("Hello scene");

    // Adds a flevaclip to the scene when loaded.
    scene.addPrefab("myPrefab");

    // Outputs "Running scene" every frame.
    scene.addScript(function ontick(scene) {
        trace("Running scene");
    });

    // Outputs "Goodbye scene" when unloaded.
    return function onunload(scene) {
        trace("Goodbye scene");
    }
});

Suppose the developer wanted to create a prefab with two onloads that would be used in a scene, and does the following:

• Ouputs the x and y positions of the prefab in onload 1
• Set the x position to 75 in onload 1
• Outputs a message every frame from onload 1
• Outputs "Hello World!" in onload 2
• Outputs the x positions of the prefab in onload 2
• Outputs a message every frame from onload 2

The related code for the above requirements would be the following:

function onload1(prefab) {
    // Ouputs the x and y positions of the prefab in onload 1
    trace("X: " + prefab._x);
    trace("Y: " + prefab._y);

    // Set the x position to 75 in onload 1
    prefab._x = 75;

    // Outputs a message every frame from onload 1
    prefab.addScript(function ontick(prefab) {
        trace("Running prefab from onload 1");
    });
}

function onload2(prefab) {
    // Outputs "Hello World!" in onload 2
    trace("Hello World!");

    // Outputs the x positions of the prefab in onload 2
    trace("X: " + prefab._x);

    // Outputs a message every frame from onload 2
    prefab.addScript(function ontick(prefab) {
        trace("Onload 2 frame message");
    });
}

/* Within engine's onload */
createPrefab("myPrefab", { _x: 50, _y: 20 }, onload1, onload2);

The final output for the above code would be the following:

/* Output when the prefab loads */
// > X: 50
// > Y: 20
// > "Hello World!""
// > X: 75
// > "Running prefab from onload 1"
// > "Onload 2 frame message"
// > "Running prefab from onload 1"
// > "Onload 2 frame message"
// > "Running prefab from onload 1"
// > "Onload 2 frame message"
// > ...

You may notice that as callbacks, the onload functions could be coded separately and added to the parameters by name.
Regardless of this, the developer can still use the specific scene or flevaclip object that will be passed to it by the engine.

How I would improve it

Callback Hell?!

If left unstructured, creating scenes, flevaclips, and more can become what would seem like nested functions inside nested functions, or callback hell, which can reduce the readability of the source code. I would try to modularize components so that they can be used with better structure and code readability.

Encourage Better Code Practices

Readability can also suffer if variables used are vague or repetitive:

What is self??? Python?! Why is it used everywhere but refer to different things??

FlevaR docs can encourage better naming conventions or function structures to increase readability:

Existing Engines Inspiration

I initially wanted to simply create onClipEvent(load) and onClipEvent(enterFrame) APIs for FlevaR, similar to Adobe Flash AS2. However, that idea did not allow multiple functions for each event, as the current callback method I use.

Admittedly, when moving on from Adobe Flash, existing game engines were too overwhelming, so I did not get a thorough understanding of how their script flows work. Maybe what they do is similar to how FlevaR does it, or maybe it is drastically different (and better). Gradually, I want to make games with other engines as well and use that knowledge to better the developer experience of FlevaR, especially related to FlevaR's coding conventions and encouraged syntax.

back to contents

Render Engine

The game engine loads, the players clicks a button (or presses a key), and they are (usually) taken to the menu screen where they can browse the options, check the credits, or play the game. For the player to know what button to press, and whether their interactions have an effect on the application, they need visual feedback. FlevaR also handles the rendering for the developer, so they only describe where each object is positioned, what size it is, and how it looks.

How it works (as well as how to use it)

All the flevaclips and scenes are drawn on the game screen for players to see, in the order of Scene, VCam, and then Flevaclip as shown in the execution system.

Render Context

Currently, FlevaR uses CanvasRenderingContext2D (context 2d) APIs to draw all in-game graphics. This API is used to draw shapes, images, text, and more.

Basic context 2d Example: Drawing a Square

To get a CanvasRenderingContext2D instance, you must first have an HTML5 <canvas> element:

 <canvas id="flevarCanvas" width="600" height="500" style="position: absolute; left: 0px; top: 0px;"></canvas>

To get the canvas' 2D rendering context, call getContext() on the <canvas> element, supplying "2d" as the argument:

const canvas = document.getElementById("flevarCanvas");
const ctx = canvas.getContext("2d");

With the context variable, you can now draw anything. The following code draws a red rectangle on a blue screen:

ctx.fillStyle = "#3B4050";
ctx.fillRect(0, 0, 600, 500);

ctx.fillStyle = "#E44D26";
ctx.fillRect(100, 100, 200, 50);
ctx.strokeStyle = "white";
ctx.strokeRect(100, 100, 200, 50);

So far, simple right? However, the following additional code will draw another red rectangle, this time rotated 45 degrees about the mid point of the first red rectangle:

// positioning to origin
ctx.translate(200, 125);

// rotating matrix
ctx.rotate(Math.PI / 4);

// repositining to source
ctx.translate(-200, -125);

// drawing
ctx.fillStyle = "#E44D26";
ctx.fillRect(100, 100, 200, 50);
ctx.strokeStyle = "white";
ctx.strokeRect(100, 100, 200, 50);

The translates are necessary because context 2d uses a transformation matrix that determines where an object is drawn. If you tried rotating without first translating to the origin of the shape, you may get unintended results:

// rotating matrix
ctx.rotate(Math.PI / 4);

// drawing
ctx.fillStyle = "#E44D26";
ctx.fillRect(100, 100, 200, 50);
ctx.strokeStyle = "white";
ctx.strokeRect(100, 100, 200, 50);

As you realize, keeping track of all the complexities required is a tedious and slow process for any developer. That is why FlevaR handles the drawings internally, and allows the developer to simply state the positions, sizes, and appearances of flevaclips.

Appearances

FlevaR has 4 appearances that can be used:

• Graphics
• Sprites
• SpriteSheets
• Paintings

To use an appearance, a setAppearance() method is provided that accepts a function as a callback. In the callback, an appearance object (belonging to the scene or prefab) is passed and contains APIs for selecting the intended appearance based on the scene's or prefab's state.

self.setAppearance(function(appearance, state) {
    if(state.moving) {
        app.useSpriteSheet("moving_char");
    } else {
        app.useGraphic("idle_char");
    }
}

Graphic Appearances

Graphics refer to any static image the developer adds to the game, via the createGraphic() method:

createGraphic("myGraphic", { _name: "nice-image", _type: "png", _path: "assets" });

Any intended scene or prefab can then use the graphic:

/* Within set appearance function */
app.useGraphic("myGraphic");

Sprite Appearances

Sprites refer to images that are dynamically created by the developer, and stored for usage. They can be created using graphics, paintings, or other sprites:

flevar.createSprite("mySprite", { _width: 100, _height: 120 }, function(ctx, {_x, _y, _width, _height}) {
    ctx.fillStyle = "black";
    ctx.fillRect(_x, _y, _width, _height);
});

Any intended scene or prefab can then use the sprite:

/* Within set appearance function */
app.useSprite("mySprite");

Trivia: Sprites were once the only appearances available for scenes and prefabs; the developer had to add a graphic, convert it into a sprite, and then use it in an appearance method. Now, graphics can be used as appearances directly, but sprites are still kept for their dynamic creation possibilities.

SpriteSheet Appearances

SpriteSheets are sequences of images that are run on loop, giving the illusion of animation. As a simple explanation, the developer would set the size of spritesheets and how they look, using graphics, paintings, sprites, or other spritesheets. Then, FlevaR would crop and frame the generated images accordingly, and store it for use by scenes or prefabs:

/* Within set appearance function */
app.useSpriteSheet("mySpriteSheet");

For a detailed explanation on how spritesheets are defined, check the documentation.

Painting Appearances

Although FlevaR abstracts away the complexitites of rendering, some developers may still want the freedom and flexibility of using the context 2d APIs themselves. Thus, FlevaR provides "paintings" to accomplish this. Developers can define a "formula" (basically a function) which will be executed each frame, drawing the object according to the developer's code and values.

Furthermore, FlevaR sends the context, x, y, width, and height of the intended object to the painting function, so the developers can customize their drawings. As safeguards to prevent paintings from destroying the entire visual canvas screen, FlevaR first draws the painting on a separate canvas of matching flevaclip size, then paints that onto the main canvas screen. That way, any drawings that exceed the size of the flevaclip is automatically cropped.

Unlike Sprites and Graphics that are stored as images, Paintings are stored as Scripts that are called every frame.
See the documentation for more details on paintings.

Appearance Association

When a use<Appearance> method is called, FlevaR associates that appearance with the particular scene or prefab. When the scene or prefab needs to be rendered, FlevaR checks the appearance type, looks for the matching appearance in its library, and after calculating the position on stage (as the usual case for prefabs), draws the image or runs the painting function. Currently, appearances are only changed if the state of the prefab or scene changes, taking after how components in ReactJS are only re-rendered when state changes.

In hindsight, this was a useless feature to use for FlevaR, as I could have simply used if statements and remove state entirely, but I need to do more research on that.

Appearance Rendering

FlevaR takes the complex matrix manipulation from context 2d off the hands of the developer, so they only state where an object is placed, and how the object looks. For each prefab, FlevaR internally sets the position of the canvas matrix, then draws the specific appearance. The benefit of providing flevaclips with predefined transform properties (_x, _y, _width, _height, _anchorX, _anchorY, _rotation) is that the engine can use these directly when calculating the matrix transforms:

function setMatrixPosition(ctx, props) {
    const offsetX = (props._anchorX / 100 * props._width);
    const offsetY = (props._anchorY / 100 * props._height);

    ctx.translate(props._x, props._y);
    ctx.rotate(numberUtils.degreesToRadians(props._rotation));
    ctx.translate(-(props._x + offsetX), -(props._y + offsetY));
}

function renderFlevclip(ctx, props) {
    ctx.save();

    setMatrixPosition(ctx, props);
    renderAppearance(props.appearance);

    ctx.restore();
}

As seen in the sample above, the engine saves the original matrix transform, calculates the transform the matrix needs to be at for the flevaclip, renders the flevaclip, and restores the matrix transform to prepare for the next flevaclip. All of this happens hundreds of times each frame, but all the player sees is the flevaclip object on the screen in its intended position, with its intended rotation, anchor, size, and appearance.

Additional Scaling

FlevaR also does more internally to accommodate resized game screens, increasing or decreasing the canvas matrix so other objects are scaled relatively, keeping consistency with the screen regardless of size (fullscreen, minimized, or otherwise).

How I would improve it

State Changes Appearances

FlevaR currently does not allow adding direct properties to flevaclips (such as prefab.myNewVar = 24) or modifying existing properties to invalid values (such as typing prefab._x = "Hello world!"). These decisions are to prevent any unexpected errors or engine crashes (since the internal engine will not know how to set the position of the context 2d matrix relative to a flevaclip's coordinates (props._x, or props._y) if it is a string instead of a number). However, I did know that developers would want to store additional custom values on different objects. Thus, flevaclips adopted state properties. Properties could be added or removed using changeState(), setState(), and useState(), methods. When these methods are called, a flag is set internally that marks the state object as modified. Then, after all scripts are ran and the render methods are being called, each flevaclip checks whether its state has been modified, and if so, calls the appearance function again, which would, depending on the definition, choose an appropriate appearance visual.

The purpose of changing the appearance only once when state changes was in an effort to reduce the potential resource intensive operations that could be performed if the developer naively sought to use<Appearance> on every frame:

/* Within flevaclip's onload */
prefab.addScript(function tick(prefab) {
    if(prefab.state.happy) {
        prefab.useSprite("happy_sprite");
    } else {
        prefab.usePainting("sad_painting");
    }

    if(Key.isDown(Key.X)) {
    // ...other code    
});

If the above code was allowed, it would be run every frame and the appearance would be set over and over, even if the state did not change.

/* Within flevaclip's onload */
prefab.setAppearance(function (app, state) {
    if (state.happy) {
        app.useSprite("happy_sprite");
    } else {
        app.usePainting("sad_painting");
    }
});
prefab.addScript(function tick(prefab) {
    if (Key.isDown(Key.X)) {
        // ...other code    
});

The above code will only change the appearance once state changes.

The Proposed Change

It would be convenient to modify the appearance directly from flevaclip events or code:

/* Within flevaclip's onload */
prefab.onClick = function(prefab) {
    prefab.useGraphic("active");
}

Rather than first having to set the appearance and then modifying state for the visual change to be reflected:

/* Within flevaclip's onload */
prefab.onClick = function(prefab) {
    prefab.changeState("isActive", true);
}
prefab.setAppearance(function (app, state) {
    if (state.isActive) {
        app.useGraphic("active");
    } else {
        app.useGraphic("inactive");
    }
});

A possible change would be to remove the setAppearance function/barrier, and leave the use<Appearance> methods available from the scene or prefab directly. To combat the potential increased intensive operations, FlevaR can simply ignore any use<Appearance> calls internally if the flevaclip is already using that appearance.

I'll have to do more research on this to determine a simplistic and developer friendly way to handle appearance changes.

Optimized Canvas Draws

Some of the biggest bottlenecks that cause drops in engine performance are translation calls, as well as ctx.save() and ctx.restore() calls being made for each flevaclip, for each frame, every second. Context 2d operations are not batched to the GPU, and are executed one by one, so while ctx.save() and ctx.restore() functions are useful, using them excessively slows down the engine.

Additionally, each transform function (such as rotate(), translate(), and scale()) performs a matrix multiplication, and multiple multiplications increase the operations that the browser needs to perform for each flevaclip, each frame. The current setMatrixPosition function performs a minimum of three separate transform calls (and more calls depending on some finer ommitted details). These transforms combined with the excessive use of ctx.save() and ctx.restore() decrease the speed of the engine at scale.

Optimizing the renderer would thus require minimizing ctx.save() and ctx.restore() calls, as well as transform calls (and lower matrix multiplications). I've recently been experimenting with an optimized context 2d drawing method that reduces the number of matrix multiplications required per flevaclip, and does not need ctx.save() and ctx.restore() calls:

function setMatrixPosition(ctx, props) {
    const offsetX = (props._anchorX / 100 * props._width);
    const offsetY = (props._anchorY / 100 * props._height);

    const yAx = -Math.sin(numberUtils.degreesToRadians(props._rotation));
    const yAy = Math.cos(numberUtils.degreesToRadians(props._rotation));
    ctx.setTransform(yAy, -yAx, yAx, yAy, props._x, props._y);
    ctx.transform(1, 0, 0, 1, offsetX, offsetY);
}

function renderFlevclip(ctx, props) {
    setMatrixPosition(ctx, props);

    renderAppearance(props.appearance);
}

There are less transform calls involved, which means less matrix multiplications. The alternatives would be to use trigonometry to calculate, as shown in responses to this stackoverflow question, as well as this very helpful article. I was able to modify the code to support flevaclips of any x, y, width, height, anchor, rotation, and even scale.

Disclaimer: Ideally I could use enough trigonometry to only need the setTransform() call (and not the additional transform() call) but due to my own math limitations, the code above was what I've currently ended with.

The advantage of this form of canvas rendering is that it can render over 1500 objects at 120fps, and over 3000 objects at 60fps:

Converting to WebGL Render Context

Browsers also provide a Web Graphics Library for rendering high performance interactive graphics without the use of plug-ins. Unlike CanvasRenderingContext2D, WebGLRenderingContext takes advantage of hardware graphics acceleration on the player's device. All this means is that WebGL is very fast. With it, one can render thousands of flevaclips per frame, at 120fps.

However, my personal knowledge of WebGL is minimal, so I could not develop a WebGL renderer for FlevaR.

Using PixiJS

WebGL, while powerful, is very complex. Fortunately, many libraries exist that abstract away the complexities. PixiJS is the most popular and flexible 2D WebGL renderer, so I have considered using it instead of developing a WebGL renderer myself.

So far, everything in the engine has been created by me, based on what I've gradually learnt, and I avoided depending on external libraries for my code to work. However, if I was to begin using a WebGL renderer for an increase in speed and flexibility of FlevaR, I may consider PixiJS.

WebGL/PixiJS Caveat

Currently, because FlevaR uses context 2d, I can allow developers to create their custom visuals for flevaclips, through the use of Paintings where the simple context 2d API is available for them.

If I switch to WebGL, there are no easy APIs they can use as Paintings, which complicates the possibilities of FlevaR's flexible render engine when you consider current alternatives:

1. Use a context 2d canvas for drawings, then render it as a WebGL texture.
   
   The problem with this is that Paintings are executed each frame, since depending on the code the developer uses, values can be changed. The process of drawing to a 2d canvas, converting to WebGL, and drawing it on the screen, for each painting on each frame, would create a bottleneck that WebGL is supposed to solve to begin with; though Graphics, Sprites, and SpriteSheets will be drawn faster, Paintings, will be slower.

2. Develop a similar API to context 2d that works in WebGL, and allow the developers to use that; to them, the syntax of Paintings will remain the same, and all appearances will benefit from the faster WebGL rendering.
   
   Unfortunately, although existing libraries exist that try to solve this problem (canvas-webgl, webgl-2d, Canvas2DtoWebGL), they were never able to implement all context 2d APIs, they became just as slow as canvas to achieve similar APIs, and they were all discontinued over 5 years ago.

3. Develop a new API the developer can use. PixiJS already provides an API that can be used to draw shapes. However, that requires the developers to learn a new syntax.
   
   This may not be a problem currently, since FlevaR does not have many developers, but it still is something to greatly consider; I'd like to keep the engine as simple as possible for developers.

back to contents

Data Storage

One of the most exciting challenges in a game is beating a highscore or collecting the most coins in a level. To keep a player coming back to your game, you can't have the game progress resetting every time the game is reloaded. For that, it is important that the game saves the progress, and loads it at a later time.

Just like other game engines, FlevaR provides an API the developer can use to allow for storing and retrieving data, called SharedObjects.

What influenced it

The storage APIs were heavily influenced by the ActionScript 2.0 APIs provided by Adobe Flash. When developing the APIs, I used these- two websites as reference.

How it works

Conveniently, all major browsers provide local storage and indexedDB that can be used to store and retrieve data on the user's device.

For efficiency and optimization, the data is often stored in the application's memory and written to storage when explicitly called by the developer. Internally, the method of storage that the engine uses (separate from the API it provides to the developer) is called a storage driver. FlevaR's SharedObjects is an abstracted wrapper around an indexedDB driver, and it also uses a localStorage driver as a fallback, where applicable.

localStorage Driver

FlevaR uses the simple localStorage.getItem, localStorage.setItem, and localStorage.removeItem functions. However, by default, each application can only store up to 5MB of data.

This limit can be increased by the application user, but FlevaR tries to provide as much as possible without the user having to worry about size constraints.

indexedDB Driver

The IndexedDB API allows rich query abilities and a larger maximum storage size than localStorage; only limited by the device's storage capacity, and operating system.

I.E. It is not something the player has to worry about. For this reason, FlevaR uses IndexedDB as storage as the default driver.

However, it is very complex for beginner developers. For example, you have to open a database, create an object store, start a transaction, make a request, wait for an operation, etc etc. I took the task of learning it enough to abstract that complexity away and provide it as a driver for the FlevaR engine. Thus, the developer only needs to focus on SharedObjects, and the engine does the efficient complex storage for them.

To thoroughly test this driver, I also referenced the API (and source) of a JavaScript library called localForage.

SharedObject Module

When a sharedobject is created, the developer gives it a name. Internally, an object is created in memory with the same name, and is persisted throughout the duration of the game. Depending on the code from the developer, this object is either stored to the device (flush), or emptied and deleted (clear). If multiple sharedobjects are created with the same name, the existing reference in memory is returned and shared at that variable location.

How to use it

Creating a SharedObject:

To start saving data, the developer first creates a SharedObject:

const mySharedObject = await SharedObject.getLocal("my_sharedobject");

All data to be saved is then stored in a data object:

mySharedObject.data.username = "Bob";
mySharedObject.data.age = 23;
mySharedObject.data.hobbies = ["brawling", "building", "reading", "mining"];

Saving a SharedObject:

To store the data to the device, the developer has to explicitly call the flush method of the sharedobject:

await mySharedObject.flush();

All the variables in the data property will then be stored.

Deleting a SharedObject:

To remove the data from the device, the clear method of the sharedobject can be used:

await mySharedObject.clear();
//The reference to `mySharedObject` is still active, but it no longer exists in memory, and `mySharedObject` is now empty.

How I would improve it

Memory Storage

Both localStorage and indexedDB APIs do not work on browsers that disable cookies.

I only discovered this when playing one of my games from an iframe in an incognito tab.

In the current version of FlevaR, localstorage or indexedDB would cause the entire game to crash when the engine tries to internally access them on browsers where they are blocked.

To avoid this, I can implement a third memory storage driver as a fallback, that only stores the data until the application is reloaded or exited.

This is definitely a disadvantage for players that disable cookies, so I can also create a default warning that gives them a message such as "Enable cookies to allow saving/loading to work."

Extensible Storage Driver

FlevaR aims to also run as desktop or mobile applications, and those platforms may require different storage drivers to store data on the device. For example, localStorage or indexedDB does not work in NeutralinoJS desktop applications. However, it does provide a storage API that can be abstracted and used as a driver. Allowing FlevaR to extend the StorageObject's internals to support other APIs allows flexibility regardless of platform.

Developers that have enough knowledge to provide a wrapper of their platform's storage API to the SharedObject can probably use that storage API for their games directly; however extending SharedObjects to support it internally can still provide flexibility to other developers that do not want to worry about each platform's specific storage APIs, and just wants to extend FlevaR's engine to support it.

Uncaching Idle Storage

Currently, all SharedObjects persist in memory until the application has been closed. That means even if the developer destroyed the shared object variable reference, it is still available in the engine, taking up space in memory. I am considering providing a free or unlink method that the developer can use, which will not delete the data from storage, but only clear it from memory.

If the developer wishes to use that object again, they will have to call the getLocal function once more.

back to contents

FlevaClips

Flevaclips are the main manipulative entities in FlevaR. They are pre-configured/pre-fabricated game objects that can be defined once and reusable in whatever scenes necessary. When the game loads, many of the visuals (buttons, sliders, game characters and enemies, textfields and more) are flevaclips.

What influenced it

Before flevaclips existed, Prefabs was the main name for entitites. However, after research and implementing Textfields, I needed a term to group them both, since they had similar positions and methods. Thus, the term FlevaClip came about, heavily inspired after Adobe Flash's MovieClips.

How it works

The main properties of all flevaclips include _x, _y, _width, _height, _rotation, _anchorX, and _anchorY. The two current flevaclip types are Prefabs and Textfields

See more information on flevaclip properties here (prefabs) or here (textfields)

These properties define the space the flevaclip occupies on the stage. For example, if a flevaclip's _x and _y positions are at half the stage, with 100 pixels _width and _height, no _rotation, and offsets/anchors of 0% of the flevaclip, it will appear from top-left to bottom-right in the center of the stage:

However, if the offsets/anchors are 50% of the flevaclip, it will seem centered on the stage:

As assumed, if the offsets/anchors are 100% of the flevaclip, it will seem centered from the bottom-right to the top-left of the stage:

The rotation of flevaclips are also relative to the anchors:

And the width and height of the flevaclip also stretches relative to the anchors:

The powerful thing about the flevaclip is that it contains enough information the developer would need to describe the transform of each object on the stage. The developer simply defines where the flevaclip is (the shape and positions), and the engine renders accordingly (as well as determine if the mouse touches the flevaclip in that position, and more).

How to use it

To create a flevaclip, you call the createPrefab or createTextfield method, depending on the desired type of flevaclip:

createPrefab("first_prefab", function onload(prefab) {
  // ...other code
});

To manipulate the properties of the flevaclip each frame, you call the desired methods and change the desired properties in a script added to the prefab:

const speed = 5;
function prefab_movement(prefab) {
    if (Key.isDown(Key.LEFT))
        prefab._x -= speed;
    else if (Key.isDown(Key.RIGHT))
        prefab._x += speed;
    if (Key.isDown(Key.UP))
        prefab._y -= speed;
    else if (Key.isDown(Key.DOWN))
        prefab._y += speed;
}
function border_collide(prefab) {
    if (prefab._x < (prefab._width / 2))
        prefab._x = (prefab._width / 2)
    if (prefab._x > _root._width - (prefab._width / 2))
        prefab._x = _root._width - (prefab._width / 2)
    if (prefab._y < (prefab._height / 2))
        prefab._y = (prefab._height / 2)
    if (prefab._y > _root._height - (prefab._height / 2))
        prefab._y = _root._height - (prefab._height / 2)
}

/* Within prefab's onload */
prefab.addScript(prefab_movement);
prefab.addScript(border_collide);

See more information on prefab methods here

How I would improve it

Removing Getters and Setters

Currently, many flevaclip properties are wrapped as getters and setters to control their limitations for the engine. For example, the _anchorX and _anchorY properties are locked between 0 and 100, and if the developer tries to set it to anything other than a number, it is set to 0:

Object.defineProperties(props, {
    _anchorX: {
        get() { return __anchorX },
        set(_val) {
            __anchorX = numberUtils.clamp(parseFloat(_val), 0, 100);
        },
        enumerable: true,
        configurable: false
    },
    // ...other props
});

Another example is that it allows the _rotation property to remain between -179, and 180, similarly to what is done with Adobe Flash's MovieClips. While convenient, this slows down the engine at scale (when hundreds of flevaclips exist at the same time).

Removing the getters and setters for the properties will remove the protection provided (meaning more things would break if the developer does something like prefab._x = "Hello world"), but it will increase the speed at scale.

An alternative would be to enable the protection as a separate internal method in the main loop cycle after the scripts are run, but before the objects are rendered. However, that option is open for experimentation, since developers can still break things during the script phase...

Re-Imagining Textfields

Currently, browsers only provide input or textarea elements for entering text, which does not allow layering within the canvas element. Thus, all input boxes would appear above the canvas. FlevaR uses a custom developer textbox that allows the player to type directly within the canvas:

The advantage of this is that it allows input textfields to act like flevaclips with flexible depths, rotations, and more. The disadvantage is that it does not work well for RTL text, non-latin characters, or mobile phones. This limitation is due to my own knowledge of trying to re-implement the feature in canvas instead.

After following along with CodeMirror's research and resources on how they implemented textfields for both desktop and mobile, I was made aware of the larger gap between what can be possible with canvas on mobile. Rather than try to re-develop textfields to support touch and drag for mobile highlighting, copy/pasting, RTL text, non-latin charactes and emojis and more, I'm considering removing the custom input in canvas and leaving it up to what is already provided by browsers.

CodeMirror Research References:

• Browser Input Reading
• CodeMirror Internals
• CodeMirror Version 6
• CodeMirror Design Doc
• CodeMirror System Guide
• CodeMirror Extensibility
• Canvas Textarea Test

FlevaR will still have layered textfields, but when they are selected, an element will appear. The player will enter their text there and it will be populated into the layered flevaclip textfield. This would work on mobile as well, since elements already have all the options necessary for selecting text, copy/pasting, prompting a virtual keyboard, and more.

This is similar to how certain game engines such as the WickEditor handles text in elements.

Additional Flevaclip Types

Game Engines like GDevelop have multiple objects, such as sprites, particle emitters, textfields, tiled sprites, tilemaps and more. Rather than one object trying to support multiple options like FlevaR (static/unchangeable text, dynamic/modifiable text, input/typable text), which increases the size for each flevaclip even when those values are not being used, separating them into multiple object types can remove the bloat and let each object type serve one specific purpose. With multiple types, the engine will also be able to create optimizations, such as only rendering the visible tiles in a tiled sprite, rather than rendering every single tile if only a piece of the sprite is visible.

Currently, FlevaR renders the entire flevaclip even if only a piece is being displayed.

Extensible Flevaclip Types (Plugins)

With Adobe Flash, multiple components can be created and imported which allow additional flexibility of developers that are not provided by the engine. Entending flevaclips will allow developers to create their own flevaclip presets, methods, and render definitions, and make them engine native or distributable to other developers.

The goal would be, specifically for tile-bsaed flevaclips, to only render displayed tiles (blue) and ignore the others (grey).

back to contents

Scenes

Generally, after the game has loaded, the player will first meet the menu screen:

After that, they can navigate to the options screens, credit screens, game screens...different sections necessary for a game.

In previous games I made (before developing the game engine), these different screens were managed by booleans or other state logic:

const states = ["menu", "options", "level1", "level2"];
const currentState = 0;
const paused = false;

if(states[currentState] === "menu") {
    // spaghetti menu code
} else if(states[currentState] === "options") {
    // spaghetti options code
} else...

However, managing the individual logics for adding and removing objects and functionality for each individual screen was always a tedious task. In FlevaR, I sought to remove that tediousness by "letting the engine handle it". Similar to existing game engines, I decided to use Scenes.

What influenced it

"Scenes are to FlevaR what frames are to Flash!"
- Danidre

This was the first thought process when developing FlevaR. Adobe Flash used frames for all their animations, and developers used those frames as different game scenes where desired.

However, the first workflow of FlevaR was mostly with code in a text editor, rather than a visual editor like Adobe Flash. Due to this, I thought it very tedious trying to mimic Flash frames with code alone: having some flevaclips stuck in one frame; having others extending over multiple keyframes; having more flevaclips in higher or lower layers, each with their own nested crazy frame scenes:

I decided to separate screens by the use of Scenes instead of frames. The disadvantage of this is that there were no layers, but the advantage was that it was simple for developers to...develop and use.

How it works

Internally, all scenes definitions are stored within the engine's library. When the developer decides to use a scene, it is loaded, executing all onload scripts, and adding all associated flevaclips defined in the onload scripts. Those flevaclips are then loaded as well and soon all tick scripts are executed each frame.

When the developer decides to use a new scene, the engine first unloads the current scene (as well as its associated flevaclips), then gets the next scene from its library and repeats the load process again.

How it is used

Creating a Scene

To create a scene, the developer calls the createScene(name, onload) method. Within the scene's onload functions, the develop declares all flevaclips they want associated with that scene, as well as the associated game logic and functionality required:

createScene("menu_scene", function onload(scene) {
    // ...other code
    scene.addTextfield("large_text", { _text: "Mountain Bell Ski" });
    scene.addPrefab("play_button");
    scene.addPrefab("help_button");
    scene.addPrefab("fullscreen_button");
    scene.addPrefab("reset_button");
    scene.addTextfield("credits_text");
});
createScene("help_scene", function onload(scene) {
    scene.addTextfield("help_text");
    scene.addPrefab("menu_button");
    // ...other code
});

The code above assumes the prefabs were previously created and defined using createPrefab() or similar methods.

Using a Scene

To use a scene, the developer calls the useScene(name) method:

useScene("help_scene");

How I would improve it

Layers in Layers

Currently, the engine can manage scenes, and scenes can manage flevaclips. Scenes cannot manage nested scenes, and flevaclips cannot manage nested flevaclips. Along with the complexity it would add for a developer, it was also out of the scope of my personal knowledge, since I did not know how to render flevaclips nested in flevaclips if the parent flevaclip had modified dimensions:

I also did not know how to perform mathematical calculations to determine if the mouse pointer was colliding with a nested child flevaclip, if it was distorted based on its parent's dimensions.

It has always been a goal to allow layers in FlevaR. I've recently learnt more about matrices, so this might be a possibility soon.

A Scene within a... Scene?

For game engines like Godot, all objects/nodes are basically scenes, and can have more scenes in them. I have not personally tried Godot, but the idea does sound like one I can explore with FlevaR.

Visual Editor (and Frames!)

Currently, I'm working on a Visual Editor for FlevaR that allows developers to mix scripting with dragging, dropping, drawing, and more, all within the browser:

There's no secret to the editor: it basically generates the associated FlevaR code required for a game.

Hopefully, even if I add complexity with layers, the visual editor will hide the tedious coding from the developer so they can have a better overall user experience. Maybe I will also be able to use frames instead of scenes?

back to contents

Virtual Camera

One of the cool features a game can have is a virtual camera that follows a player:

These allow the developer to create more objects on one screen, and does not limit the viewable area of the player to only that screen:

Some game engines provide virtual cameras out of the box (Unity), and other game engines require additional components from developers (Adobe Flash). FlevaR provides a virtual camera that the developer can easily manipulate, with similar properties as flevaclips (_x, _y, _width, _height, _anchorX, _anchorY, _rotation), and additional properties (_xScale, _yScale).

Trivia: The virtual camera took me over 5 months (October 2020 - March 2021) of active and inactive development, to successfully complete!

How it works

The idea of VCams in FlevaR is to capture what is directly under the virtual camera in the current scene, and project that onto the viewable screen for the player. The canvas element does not resize along with the VCam, but instead the contents of the scene are stretched to fill the screen.

In order to accomplish this, FlevaR internally transforms the context 2d matrix such that all future positions set by flevaclips are relative to the VCam's projection.

Visual Examples

The following samples will give a better understanding of how the dimensions of the VCam are projected onto the resulting screen:

Suppose there is a 400 x 400 pixels video game with a colourful background:

If you add the default VCam, the developer would recognize no change:

By default, a VCam is created with the same size as the canvas screen (in this case, 400 x 400 pixels), and the anchors at 0 (top left of the VCam).

To demonstrate positioning, suppose you set the VCam's _x to 150 and _y to 120. The following results:

The entire context 2d matrix is shifted so you only see the pixels that the VCam is on top of.

Let's explore more, this time setting the anchors of the VCam to 50% (the center of the VCam):

Although the x and y positions haven't changed, the anchors change the center of VCam rotation.

Rotations...let's see what would be projected if the VCam is rotated 45 degrees clockwise:

Since the canvas element itself cannot be rotated, the entire game screen is rotated to reflect how it would look upright to the player.

Similarly, if we manipulate the size of the VCam, the projected view will also be stretched to fit. Let's change the _width and _height of the VCam to 250 pixels each:

With a smaller VCam, a smaller portion of the scene will be projected onto the screen, making the objects look larger.

The inverse can be observed as well; with a larger VCam, more of the scene would be projected onto the screen, making the objects seem smaller. The following example uses a VCam with 500 in size, 50% anchors, and no rotation, positioned in the center of the stage:

Things get weird if you resize the VCam to a different aspect ratio than the game screen.

A 200 x 400 VCam on the 400 x 400 screen looks horizontally stretched:

Similarly, a 400 x 600 VCam on the 400 x 400 screen looks vertically stretched:

The results get even more questionable when you combine rotations with differently scaled VCams.

Here is the 400 x 400 stage with a VCam centered, with 200 width, 300 height, and rotated 60 degrees:

It looks weird, but trust me, it is projected accurately.

How to use it

FlevaR provides a VCam module that developers can use to manipulate any of the properties of the virtual camera:

const sVal = 15;
const rVal = 3;

if(Key.isDown(Key.A)) {
    VCam._width -= sVal;
} else if(Key.isDown(Key.D)) {
    VCam._width += sVal;
}
if(Key.isDown(Key.W)) {
    VCam._height -= sVal;
} else if(Key.isDown(Key.S)) {
    VCam._height += sVal;
}
if(Key.isDown(Key.Q)) {
    VCam._rotation -= rVal;
} else if(Key.isDown(Key.E)) {
    VCam._rotation += rVal;
}
if(Key.isReleased(Key.R)) {
    VCam._rotation = 0;
    VCam._width = 400;
    VCam._height = 400;
}

How I would improve it

Consistent API

Some naming conventions in the APIs are inconsistent, such as _anchorX, and _xScale. I originally used _anchorX as an additional property separate from Adobe Flash AS2's syntax, but when adding scale APIs to VCam, I used the _xScale as implemented in Adobe Flash AS2. For consistency, I should either choose the naming conventions as _anchorX and _scaleY, or _xAnchor and _xScale, rather than the confusing interchanged properties.

Multiple Virtual Cameras

I once had many difficulties creating a split screen two player game with Adobe Flash AS2; I first needed to create duplicate movieclips for every player, enemy, and world object, and nest each player's world within a cropped version of the world to give the illusion of a split screen. It would have been much easier if I could create the world once, and add 2 virtual cameras, making one follow player 1 on half the screen, and making another follow player 2 on the other screen half.

Additionally, for games with minimaps or "camera" systems, it would be very powerful if the developer can use a VCam within the engine to project a portion of the world on only a portion of the screen, rather than having to create duplicate flevaclips for maps or camera objects.

Due to knowledge limitations at the time, I could only accomplish one VCam after 5 months of efforts, so I left it at that. However, FlevaR has plans to support multiple VCams in the future. Instead of only setting what should be projected on the screen, the developer will be able to configure what would be projected, and where on the screen it will be projected! If the developer desires, they can have the default VCam rendering the player, and additional VCams projecting a room, and displayed on numerous sides of the screen. Here is how it looks in theory:

Looking complicated? Here's a breakdown of 3 virtual cameras. They can project any size, position and rotation of the scene, and can be displayed at any size, position, and rotation on the screen:

The ending result will have projections of each VCam at their respective locations on the screen:

As you noticed, VCams can be layered too!

Current Virtual Camera Development

Because of recent progress/optimizations I made on context 2d's draw calls, the experimental render engine can already support multiple VCams with configurable projections and views. Best of all, it still renders over 1000 objects at 60fps:

back to contents

Event Handling

Numerous frameworks or game engines mention event handlers (to catch when a mouse is pressed, a key is typed, or otherwise). Even Adobe Flash APIs had events such as onRelease, onPress, and more. Aside from a very hacky onClick() event on flevaclips, FlevaR currently has no built-in APIs that capture events and dispatch them to flevaclips or scene objects for the developer to use or modify. At the time of developing, it was not a high priority item for the engine, and later on proved too difficult to integrate with the developed architecture of the engine.

One example of the difficulty is trying to add a core.onMousePress event. Browser events, for example, has a target property that stores the element that received the event, so instead of adding 100 onMousePress events to each element, the developer can set 1 onMousePress event and use the target property to determine which of the 100 elements was pressed.

However, Flevaclips can be any determined sizes or positions, and can change their transform very dynamically. Thus, if FlevaR had to determine which flevaclip the mouse hovered each frame, it would need to loop through all flevaclips on the stage. FlevaR had no existing way to optimize flevaclips in chunks or BSTs based on fixed sizes, because the developer can alter the transforms such that the chunk sizes would not be compatible. This is also a problem because depending on the size of a flevaclip, its _x and _y positions can be off the visible screen, but its _rotation and size would be such that it still crosses the view, hence it will need to be checked for mouse events as well.

Chunk-based optimizations such as that is left up to the individual developer, based on their particular game; they will know what constraints to use

To get around this currently, instead of looping all flevaclips for mouseovers, FlevaR only loops over flevaclips that the developer explicitly added a onClick() event to; this saves loop resources each frame.

I'll have to do more research to find an optimized way to loop these things regardless of their positions, sizes, offsets, and rotations; for hundreds of flevaclips, many times per second, at performant speed.

Currently, the goto APIs provided are simply Mouse and Key modules and their isUp, isDown, isPressed, and isReleased methods.

back to contents

Root Proxy

One of the most powerful (but slow) APIs FlevaR provides is the _root property. It is defined as the engine's stage, used to reference stage properties and methods, or flevaclips within the main lifecycle of the application.

What influenced it

Adobe Flash. Adobe Flash. Adobe Flash.

Adobe Flash's AS2 API provided a _root object that gave the developer access to many properties in the application:

1. If you gave a movieclip an instance name of "character", you can access it with code through _root.character.
2. If you wanted to get the mouse positions, you can access them with _root._xmouse and _root._ymouse.
3. If you wanted to use core methods or go to other frames, you can with root (_root.gotoAndStop()).
4. If you redefined an existing accessible object (_root._xmouse = "Hello world") it would be ignored.
5. If you tried to access a non-existent root property (_root.noProp) or nested root property (_root.my.values.do.not.exist), Flash would simply return undefined instead of throwing an error.

How it works

I wanted to also provide a _root property with the flexibility allowed in AS2. The best way (or rather, only way) to do that in JavaScript was using a Proxy object. These objects intercept and redefine fundamental operations for the object.

The FlevaR proxy is a very complicated one; when trying to access (get) a property, the following sequence is followed:

1. If toString is accessed (_root.toString()), return the string "[root Stage]".
2. If reserved properties (_root.type) is accessed, return their value.
3. If a string matching an existing flevaclip's instance name (_root.character) is accessed, return the flevaclip and/or property of the flevaclip (_root.character._x).
4. If a property of the stage (_width, _color, etc) is accessed (_root._color), return the value.
5. If a method of the stage (attachPrefab(), removePrefab(), etc) is accessed (_root.attachTextfield()), call the method on the stage.
6. If a string matching no existing property was accessed (_root.noProp), return "undefined".
7. If a non-existent object was accessed, return a nested root proxy that just returns "undefined" instead of errors for missing objects and missing object properties. It treats each new key in a nested object as another proxy object, so _root.my.values.do.not.exist would return "undefined" instead of Error: cannot access "values" of undefined object: "my" as is usually expected in JavaScript.

Trivia: The nested root proxy on step 7 of the sequence is called a floxyChain for FlevaR Proxy Chain. See the entire internal code for FlevaR's _root proxy here (Line 7573 of the engine)

A similar sequence is followed when modifying (set) a property:

1. If reserved properties are modified (_root.type = "flobtives"), silently ignore.
2. If a string matching an existing flevaclip's instance name (_root.character = "Hello FlevaR!") is modified, silently ignore.
   The code _root.character._x = 5 will work because _root.character gets the flevaclip, and flevaclip._x = 5 modifies it as expected.
3. If a property of the stage (_width, _color, etc) is modified (_root._color = "green"), set the value of the stage property.
4. If a method of the stage (attachPrefab(), removePrefab(), etc) is modified (_root.attachTextfield = 21), silently ignore.
5. If a non-existent object is modified (_root.my.values.do.not.exist = "yes I do exist now", silently ignore.
6. Silently ignore anything otherwise.

Root Order Priority

As noticed, the simplified order priority when accessing or modifying root properties is as follows:

• FlevaClips
• Stage Properties
• Stage Methods

How to use it

Let's start with an empty unmodified scene:

Change the stage's colour to a blue colour:

_root._color = "#3B4050";

Add a prefab with instance name of "myCoolPrefab" to the stage:

_root.attachPrefab("my_prefab", { _x: 45, _y: 60, instanceName: "myCoolPrefab", attachedName: "myAttachedClip" });

Modifying the attached prefab:

_root.myCoolPrefab._x = 100;

Removing the attached prefab:

_root.removePrefab("myAttachedClip");

As noticed, the prefab is located for removal through the attachedName string.

Due to the order priority, giving flevaclips instance names that conflict with stage properties/methods causes the _root accessor to reference the flevaclips instead. This is consistent with Adobe Flash AS2's APIs as well. Thus, assuming a flevaclip on stage has instanceName: "_color":

/* Within scene's onload */

// add flevaclip to scene
scene.addPrefab("my_prefab", { _x: 150, instanceName: "_color" });

Attempting to change the scene's _color will silently fail:

// attempt changing stage's color to blue
_root._color = "green"; // <-- silently fails

// trace _color property in _root
flevar.trace(_root._color);

// > [type Prefab]

How I would improve it

Convert to Root Object

Rather than a slow proxy, an object should be used to store the dynamic values.

Currently, any stage properties are accessed from an internal Stage module, which also uses getters and setters to prevent bugs (in case the developer types stage._width = "hello world", crashing the game, since many of the internal components in the engine depends on the width of the stage being a number value). A proxy on top of getters and setters means an even slower engine. I would optimize this by placing the properties and methods directly on a _root object, and accessing them there internally as well.

Currently, root loops through all active flevaclips to see if an instance name matches the desired key being accessed on the root. To optimize this, flevar can cache flevaclips by internally adding all flevaclips with instance names to a dictionary/bucket of the root object. Thus, checking for an existing flevaclip by instance name would check the cache immediately and remove the loop that increases with the number of active flevaclips.

Although these optimizations can remove the proxy, getters and setters, and increase the engine performance at scale, the developer would no longer be as protected as before: bad code such as _root._color = 5; and _root.my.values.do.not.exist would cause unexpected results or crash the engine with errors. Such is the sacrifice to be made for speed and optimizations.

Separate into Distinct Modules

Unless accustomed to by developers, having one object store properties for separate modules, and depending on the developer to remember priorities and possible overwrites, while flexible, can become tedious. Separating properties into more explicit modules can help:

• Put all stage properties and modules into a provided Stage API: (Stage._wdith, Stage._colour, Stage.attachPrefab(), etc)
• Put all mouse properties in its Mouse Module: (Mouse._x, Mouse._y)
• Use explicit functions for accessing flevaclips: (getFlevaclip("myCoolPrefab"))

The _root object may stick around for convenience, but maybe the module separation can improve explicitness and developer experience.

back to contents

Performance Disclaimer

Numerous times I may mention a feature being "slow at scale" or "affecting performance" in the engine. Do note that these issues currently only arise when there are hundreds of flevaclips active at once:

FlevaR can handle an average of 400 active flevaclips at 60ps, which is much more active flevaclips than an average scene would need:

These drawbacks are due to multiple reasons, such as:

• the canvas2d render limitations
• the powerful but slow root proxy object
• general bad design (spaghetti code) of an earlier/naive Danidre developing the engine

Those caveats can be mitigated though, but that currently depends on the individual skills of the developer. The example below uses paintings and only considers the position of the object, not the width nor rotation. Thus, no transforms are required, allowing up to 4000 objects rendering per frame, with 60fps:

If they want to create a Shoot 'em up game, they can use one flevaclip with a painting for all bullets, rather than thousands of flevaclips for each bullet.

back to contents

FlevaR's Future

The journey away from Adobe Flash took me on a learning journey and I had the most fun developing the game engine.

Funny enough, only after I created my engine, I discovered many existing JavaScript game engines and frameworks, such as CraftyJS, CreateJS, ImpactJS, Platypus, MelonJS, Wick Editor and so much more! Before that, I could have only found Phaser and PixiJS, so I thought those were the only existing JavaScript game engines or frameworks.

The variety in JavaScript game engines would get one thinking, why use FlevaR? Why not use an already existing game engine? I ask myself that, too! However, most of the frameworks listed are archived/outdated/discontinued. Additionally, FlevaR's goal is not to compete with established game engines such as Phaser. Rather, it aims to be a declarative JavaScript game engine, with APIs similar to Flash. It targets beginners and promotes a simple easy environment for developing applications. While being friendly, FlevaR's APIs also allow for complex applications if the developer needs it, and with JavaScript as the main language, it is easy for existing web developers to pick up and use it! All the abstractions from the browser and internal modules I stitched together is to make that possible. FlevaR provides; Developer decides.

Future Plans

Engine Re-Write

A FlevaR re-write is definitely planned, where I explore all the proposed optimizations for different modules. I'm currently in university, so the re-write may be a year-long process.

FlevaR Editor

I've since been working on a visual editor for FlevaR games, that can transpile applications to the browser or as a desktop app. Many of the visual examples in this article was made easier through the drag-and-drop editor.

Note: The editor is in heavy development!

Port Flash Games

The original goal was for me to learn to make games in a new language/engine, and port my old Flash games. Currently, a Flash Player emulator called ruffle exists, allowing my old Flash games to run in web browsers once more. However, it is still a future goal of mine to remake my Flash games in FlevaR.

Develop FlevaR Games

Although I work on the engine, I still want to make games, so I plan on using FlevaR for many more games. That way I can continue to test the user experience of the engine or fix bugs that may be discovered.

Until I get a team dedicated to finding bugs or assisting with engine development, I'll have to be both developer and tester!

FlevaR for Android/iOS

I created a Patreon for the development of FlevaR. With the remake of FlevaR, I also want to develop APIs to support touchscreen, so applications can work on mobile phones. I also want to provide services that can package FlevaR applications for Android and iOS devices.

FlevaR Website Portal and Additional APIs

One goal is to provide a portal for FlevaR web applications, similar to portals that exist for games made with Godot, GameMaker, or GDevelop. Users will be able to view and rate other FlevaR games, or fork the source code of games if permitted by the developer. Additionally, FlevaR APIs such as highscores and medals will be implemented to take advantage of the user system and bring more rewards for both FlevaR developers and players.

back to contents

Conclusion

FlevaR has come a long way, and still has a long way to go; I am passionate about developing this engine and learning more every step of the way.

This article could not be done without the Epic Hashnode Writeathon, which encouraged me to write my dream article; this is something I've put off for almost 2 years!

This article was quite a read, so thank you for making it to the end. Hopefully it shares coherent insight on how you can use browser APIs for your own purposes. Maybe you do not need an entire engine; maybe you only need an asset manager, or a rendering system.

Regardless, I hope this article can serve as a gem for future website explorers or gamedev enthusiasts, just like many articles before this one helped FlevaR get to where it is!

It all started when I brainstormed a declarative game engine that'd be based on callbacks and contain similar features to Flash. I went straight into development. Out came FlevaR, my custom game engine.

The name idea came from "FlevaPack", a mini API for easily manipulating and auto resizing DOM elements. Since I decided to turn it into an entire library, I called it Flevapack Revolution(alized); or FlevaR.

Coincidentally, I found out that the next Ludum Dare Jam was approaching in one week, so the "meme" became whether or not I can create a game with the engine. The race to develop the main features before the Jam begins was on! Audio manager, textures, spritesheets, objects, built-in collision...all spaghetti coded throughout the week until at last, Ludum Dare 46 was upon us.

Game Jam

Geta Game Jam was also occuring throughout the same weekend; thus the meme was to create a game that'll possibly fit both jam themes. But..I needed a team.

I submitted a last minute post explaining my situation (trying a new "engine", only starting 24 hours into the jam, leaving me with 48 hours for the jam) and was able to get an artist and a music composer. Anxiety spiked, since I feared the worst! (getting great assets but making a terrible game) This was no longer a meme; this was serious.

Theme

Ludum Dare's theme was "Keep it Alive".

Geta Game Jam's theme was "Something is Missing".

So we had to create a game that merged those two themes! 😃

Brainstorming/Development

The brainstorm session began. I went as far as using idea generators, reading blogs, and finally, bringing my high school friend onboard. I needed someone to work on gameplay and design, while I focus on programming, so that was his task. But throughout the project, it still felt like ultimately, I was the director, saying "yes" and "no" to assets, and requesting opinions on everything. Saying "I need this", or "Can you get me that" instead of being told "The game should do this."

Cons

One limitation was that most of the considerations were always "could your engine handle/support this". A small con though, since it was actually able to handle everything thrown at it (with a few tweaks here and there).

Another con was that, since I was occupied 24/7, there was no one to focus on posting "progress" screenshots to build hype of the game while in development.

Ideally, I wanted to work on the game while other members focused on setting up the submissions page and all that, but in the end I lacked the confidence to ask anyone to do things out of their talents, so I ended up doing it myself, last minute.

As a result, I ran out of time with the game, and had to rush adding menu screens and more during (and a bit past) submission hour.

Pros

The artist was able to whip out some amazing levels design. And after working on the mechanics for most of the jam, adding the graphics was a breeze.

The music composer's music was mindblowing! Easily able to adjust the music and increase intensity and chaos, or include soothing ease where required.

The designer came through with many riddles to implement, in sync with the assets provided. And, I was able to split some of the programming work (such as collision) to him, so I had more time to work on other things.

I've never actually known about the many different resources that goes into making something, and I appreciate every aspect of it now.

Results

The results were...underwhelming...AT FIRST!!

But expected, I tell you! 😅

Reasons/Excuses

I call them excuses since that's how I analyzed them to make myself feel better:

1) It turns out, MANY developers decided to participate in the jam this event. Compared to the usual ~5000 signups and ~3000 games, this Ludum Dare saw ~10000 signups and ~5000 games.

LD45 Statistics

LD46 Statistics

That means I had ALOT of competition. Maybe more elite teams joined in for the event. 😄

2) It's a result of a game I made in a meme engine. How far did I expect to get with it?

3) There were many limitations and inevitably, I ran out of time. There're many things I wanted to add to it (and still do) but it's better left as it is.

Comparisons/Gotchas

Compared with my previous game:

Bob the Brawler placed #541st overall out of 1885 Jam entries, being ranked in the top 28.7% of games.

Miscen...Again!? placed #1131st overall out of 3576 Jam entries, being ranked in the top 31.6% of games.

That's a small drop in relative placements.

Similarly, looking at scores only, Miscen...Again!? beat Bob the Brawler in every category except Fun.

I don't blame it, a riddle game doesn't have much action, compared to a beat-em-up quick-paced-brawler.

My highest score was the audio! With 3.815 stars! I placed in the top 10% of games in that category!

The art was a close one too! BtB has a great artist as well, that explains why the ratings were so close!

Honest Disadvantages

To be honest, I was pretty bummed out about last Ludum Dare's results, where I played and played and rated lots of games, obtaining 100+ reviews on my game, which all seemed to be positive reviews. Yet, the ratings at the end didn't reflect all the positive feedback. I was betrayed by developers who wanted good ratings on their games! 🙃

As such, I concluded, I'll just play the minimum needed to get 20 reviews, then leave it there until results day to see if I do better this time. And even if I tried, I couldn't feel the excitement to play and rate games every single day; so I left it at that.

So, it is an illusional victory to compare Bob the Brawler's 114 ratings to Miscen...Again!?'s 29 ratings. Who knows, maybe the average stars would have lowered if I received 100+ more? Even though I tried to "cheat" the system, it didn't change the outcome much, which I conclude is a reflection of the game itself.

Well, it doesn't matter anyways. I'm not hung up on the results anyways since it was a mix between two jams. I was really excited participate in a team this Jam, and am really contented with what I was able to bring out of it. I figured I'd complete it before uploading it to other game portals (such as Newgrounds), but in conclusion, I'll leave it as it is, flaws and all.

I am satisfied.

So...what's next?

Engine

During the 3 weeks of ratings and playing games, I've been working on expanding the FlevaR Engine. It's evolved into more than a meme. I was able to retrieve the files of my old flash games from my first wix website, and that further motivated me to complete the engine.

I plan to further develop it and port some of my old Flash games to JavaScript, hopefully before 2020 ends. As well, I'll need to standardize the engine and complete the first official rollout of the wiki so other interested developers can get started with it.

Collaboration

I prefer to have someone onboard to do the world design and story building or giving meaning behind games. I understand that requires a lot of creativity and time. So in future projects, I'll also look for someone with that skill. As for game hype during development, I may also need to look for a marketer (someone solely responsible for the social media setups and advertising of the game during development and a while after release).

In my past collaborations, my role was basically "Give Danidre the assets, he'll handle everything else forever, bye."

Hopefully, I can maintain communication (if even a little bit) with team members and hopefully my role becomes more like "Create assets and give to 'the team' to incorporate it with other assets and designs and merge into one game"...unless of course the general idea is to spontaneously join, create, leave. 😂

Because it felt like I hired freelancers...for free, rather than briefly joined a team and built something. Hopefully I can find an area/create an environment in the future where responsibilities are more evenly distributed at least.

Future Game Jams

I see myself running through many game jams in the future. Most will be about testing my (currently developing) engine, as well as trying to see what fits with "team organizing". Planning itself is an important thing, so hopefully in the future I can get more of that checked, so more time is spent efficiently instead of rushing and worrying.

FlevaR

You can look out for another blog with more information on project's I've been working on in the past 3 months. As usual, you can join my Discord Server or follow me on Twitter if you want to keep updated with everything or talk development. Until next time, thanks for reading! 😃

I've been learning React recently, and handling error messages separately in my React Project, and wondered 🤔:

"What if you can merge them together?"

So I tried this:

useErrors.js

It's pretty self-explanatory, but essentially I define a useErrors function that creates an error state. Then, within that same function, I create an Error Component, which checks if an error exists. If no error exists, it is set to false; any other value would mean that there is an error.

Thus, the Error Component renders accordingly, and the useErrors function returns that Error Component, along with the setError function.

Usage:

test.js

The useErrors function is handled 4 ways:

• import useErrors from "./useErrors"; - imports the function.
• const [Error, setError] = useErrors(false); - creates the Error state, passing in the default error value (a value of false is automatically hidden), and returns the Error Component, as well as the setError function.
• setError([<value> | false); - invokes the function to set the error message. A value of false is hidden; any other value is displayed as the error message.
• <Error /> - the JSX to render the error message. (Notice no props are sent, yet it works?)

When running the code, the error is displayed:

And, when ready, it can be closed (which just sets the error state to false)

More Testing:

To further test, we can create a loop that sets random error messages and clears them:

test.js

It even works when you create multiple Error States (different names for different messages), and you could reuse the same Error Component multiple times on the page and it'll React the same for that setError:

But... how? Why?

From my understanding, React Components are reusable, either if they're functional or class-based. And the usual way data is sent/updated per Component is either through state or props. So how does a variable from a parent function run down into that Component, while being unique to that one instance of error message?

• Is any data leak happening?
• Are there resources out there that can educate me on what I'm currently doing?
• Is this bad practice? I lack knowledge of the terminology for such a thing, all I know is...it works

Until I've successfully created commenting on posts to this website, you can find me on Twitter @danidre or join my Discord server. Feel free to message me on the Nodeiflux server and share your thoughts!

It's possible it's wrong...but it works! 😉

2019 has come and gone, and many sudden changes occurred:

• Graduated from high school
• Learnt and created my new website
• Participated in my first Ludum Dare Jam in years!
• Successfully moved away from ActionScript2.0 (Flash) to Javascript.

More development on BtBIO

I took November to learn about multiplayer, and worked on this project. A multiplayer version of my Ludum Dare game, using SocketIO and NodeJS to work on browsers. I plan to continue working on this game until I've carried everything in the singleplayer game across.

Development and collaborations on other projects

I'm interesting in participating in more game jams, as well as getting more experience in collaborating with other developers on other games.

Additionally, I plan to learn React and create more applications or websites, as well as continue building/adding features to this website (user accounts, comments, user messaging, etc).

Job employment

Since I've recently graduated, I need to get working experience. Ideally, I'd like to be employed at a tech company that also works on games or websites; but for now, anything that could give experience.

Artwork

I'm no artist, but I do find joy in doodling here and there.

I do hope I can work on these more and possibly add a doodles section to this website as well!

Moving forward into 2020, there're lots of things I'm excited to do; some with higher priorities.

Game-making would be the most challenging change, as I hope I can try a new genre (so far, it's always been collision-based games). I'm not sure what new games I want to make yet, but the idea of non-collision remains. And...maybe earn a few bucks in the making? 😂

Follow me on Twitter @danidre or join my Discord Server to keep up to date with any changes. But until next time...

Stay tuned

I participated in my first collab Ludum Dare Jam; now results are out. It's bittersweet.

• Overall: 541st (3.473 average from 114 ratings)
• Fun: 417th (3.438 average from 114 ratings)
• Innovation: 861st (2.784 average from 113 ratings)
• Theme: 1052nd (2.383 average from 113 ratings)
• Graphics: 380th (3.795 average from 114 ratings)
• Audio: 334th (3.444 average from 110 ratings)
• Humor: 413th (3 average from 106 ratings)
• Mood: 650th (3.241 average from 108 ratings)

wuuuut, but I had so many ratings, and good karma~

Quality over quantity, gets the cake!

Not like that's a bad thing, that's how it should be!

so then why was 9/10 of the reviews "excellent game, amazing graphics, audio fit the theme, fun gameplay~"

Deceptive much?

Well, I guess people did want their games played. And don't get me wrong, I enjoyed most of the games I played 🤣

So I guess my game was just bad?

The trend in the top 100, unless your game is a globally popular one, once 20-40 people voted on your game and they're all your audience, that'll sure trump 100+ of varying audiences with different tastes for varying genres.

but saying that is making an excuse, right?

No copping out, do better next time.

It goes back to the saying, if my game was better, the results would have shown that. Because there are the rare top 100 that have 150+ votes. And unless mine was on that caliber of awesomeness, I shouldn't expect such glorious results 😂

but what about the other amazing games that didn't make it?

Tactics! Skills!

Bloodless was the top jam game during votings; it placed 97th overall. Other tops, weren't as lucky. Many of these results surprise me, as I genuinely thought hands down, that they'd make it.

As for the top 100 games; they did so well to keep their ratings just above the Danger Zone (games ordered by 20 votes or lower), and their personal reviews below the Smart Zone (games ordered based on how many reviews their author made). Because I could not find them 😅

was that their master plan???

Well, I'm new to all this, but it doesn't change my personal experiences earned.

Lessons learnt:

• Maybe if: I turned it into a puzzle game, it'd have done better. Many people liked the idea of a puzzle brawler. But I barely got time to complete the Brawler, who'd have time to delve into a new category of gaming like puzzles, especially as this Brawler was a new game genre for me as well!
• Maybe if: I aimed for only the minimum ratings (20), results would have generally been higher numbers? But these extensive ratings are what pushed me to take this game further!
• Maybe if: I voted minimally, I too would avoid my game appearing much. But who wouldn't want to play all these games! Besides, what's the point of Ludum Dare if you just make a game, drop it in, and move on!? (the main objective is to start something but that alone is boring; sharing/interacting is fun!)
• Maybe if: I listened to the audience and changed the controls, it'd have been less spam-feely. But 3/4 of the players seemed to love it! Besides, this is what I envisioned for this game! Regardless of if it was well received or not.
• Maybe if: I made a better game, results would have been better. But it's possible the system is flawed; or not. It is what it is.

Overall:

• It was amazing making a game for the first time with an artist. @AXLplosion was able to take all my ideas and bring them to life! I'm just sad I couldn't make the game better for his sake.
• I'm satisfied with the progress I made, utilizing game libraries and APIs I started working on in preparation for the event; call them my own "engine".
• I'm amazed by the game I accomplished, and I'm excited to continue building on it did someone say multiplayer 👀; I did not know what I was getting into when I decided to make a Brawler, and I must say, the spaghetti code was worth it!
• I'm grateful to Ludum Dare for the initiative they make to prompt a game, it really pushed my limits and helped me grow; looking forward for more competitions.
• I'm just disappointed with these results.

But hey, at least Bob the Brawler is Frontpaged on Newgrounds (at this time of writing)

Seeing it climb from Daily Pick to Popular Game to Frontpaged was an excitement of it's own 😆

Moving on:

Bob the Brawler is my Ludum Dare entry. But it did spark some ideas I'm willing to expand on, as well was include suggestions from all the reviews on the game.

In addition to that, I'm also dabbling in some multiplayer experiments, developing my own systems for Client-Side Prediction and Server Reconciliation, Entity Interpolation, and Lag Compensation, based on these articles from Gabriel Gambetta.

get a friend or another window, and just move around in this canvas. it's just a test to see how websockets work, so tell me if it lags: multiplayergaemtest

But as this event is up and over, I'm going silent for a while. Congratulations to the winners!

See you next year April!

Follow me on Twitter or join my Discord Server to keep up-to-date on any activity from me.

It’s been 4 years since I’ve last entered a game jam! Ludum Dare 29 - 34 had game after game from me.

Then school took away my time…. 😔

Until now! Highschool’s finally over! 😄

I’ve spent the July/August holidays learning, and have made this website. A great improvement from the click and drag website I made back when I was 14.

Thus, I finally have somewhere to host all the multiplayer games I hope and dream of making. 😛

But, there’s only one problem… flash is dying! 😪

Inevitably, I soon learned and adopted Javascript and HTML5 canvas, as it was very similar to ActionScript2.0; so I began working on my own game engine, which includes:

• my fully functioning and resizable/scaleable canvas panel
• my own audio system
• my own Highscore API (for users with accounts on my website)

So...Ludum Dare?

Yes! I’m excited and ready to finally participate in Ludum Dare once again! I’m in!

Additionally, I'll be teaming up with AXLplosion! He will be creating all the art for the game. 😃

tools tools TOOLS:

• Software/Engine: Pure Javascript + HTML5 Canvas (I want to learn another engine but haven’t gotten there yet. Maybe Unity? Haxe?)
• Sprites/Art: @AXLplosion
• Sound effects: SFXR/BFXR/JFXR: (Very, very, basic sound effects)
• Game Music: LMMS/FL Studio/Bosca Ceiol/PixiTrack: I’m probably going to download free music and sound effects (if I use music at all) 🤣

Streaming?

I don't know the outcome and what to expect, but I plan on streaming the process.

Be sure to follow me on Twitch and turn on notifications so you get alerted when I go live.