Forem: Caleb Anthony

Creating and working with anonymous users in Laravel

Caleb Anthony — Mon, 08 Aug 2022 20:05:58 +0000

First off, I'm defining an "anonymous user" as the user who signs in via a "guest login". A one-tap way to create a new guest account and get in-game to try things out without pledging your email or committing a new password to memory.

With that out of the way...

A nagging issue I see in the PBBG (persistent browser-based game) space is games with little to no information on the home page other than a login and registration form.

New players want to know what your game is like! And most people are unwilling to fill out a registration form to get a peek at it.

The easiest (and most oft-requested) solution to start is adding screenshots to your home page. Show potential players what your game looks like. Explain the major features. Sell your game!

The next-best solution (in my opinion) is to add a guest login.

Allow your future players to tap a single button, get in-game, and get their feet wet. All with no commitment.

Sure, you could design a walkthrough or a tutorial. But most of the types of games we're creating interact with the database very early on. While you can mock out some of the details by storing user data in the session (for example), I have found it much easier to just create a concrete User implementation. That way I can easily tie it to other concrete models like inventory systems and more.

Then, after they're killed their first few monsters or started their first kingdom or completed their first quest, let them know they need to register to save their progress! Players who are going to stick around will happily register, while those who don't like your game will fall off.

Some of the marketing benefits of this type of system:

You get a much lower bounce rate on your home page.
You get to design your onboarding process clearly and concretely for new players.
You get better data and metrics for how many players register, or where exactly they got stuck in-game.

So let's walk through how I designed the anonymous user functionality for Trounced (new kingdom-builder browser game) in Laravel.

1. Update your migrations

The users table that comes with a new Laravel installation requires that you have both the name and password fields filled out. We'll update those so they can be nullable.

Schema::create('users', function (Blueprint $table) {
    $table->id();
    $table->string('name');
    $table->string('email')->nullable()->unique();
    $table->string('password')->nullable();
    // Your other table fields here...
});

The result being that you can now create users without any email or password at all.

Great!

2. Create a Guest Login controller

I created a new controller to handle all the guest logic in one place. The first method we're going to add is a one-click guest login. We'll add the registration method to it later.

class GuestLoginController extends Controller
{
    public function login(): RedirectResponse
    {
        $randomNumbers = rand(pow(10, 5 - 1), pow(10, 5) - 1);
        $guest = User::create([
            'name' => "Guest{$randomNumbers}",
        ]);

        Auth::loginUsingId($guest->id);
        return redirect()->whereverYouWant();
    }
}

This lets you create a new user with a random 5-digit number after the name 'Guest'. Remember, we don't need any other fields to create a valid user.

Now wire up this route to a button on your home page. I'd also recommend sticking it behind some kind of rate limiter so you don't get any bad actors abusing your system.

// app/Providers/RouteServiceProvider.php

RateLimiter::for('guest-registration', function (Request $request) {
    return Limit::perMinute(2)->by($request->ip());
});

// routes/web.php

Route::post('/guest-login', [GuestLoginController::class, 'login'])
    ->middleware(['throttle:guest-registration']);

3. Interacting with 'Guest' users

At some point we'll want to encourage our guests to register, but for now we will interact with them just as guests.

The easiest way to check if a user is a guest or not is by seeing if their email is null.

I have opted to put this as an attribute on the User model to easily tell if a user is a guest:

// User Model
public function isGuest(): Attribute
{
    return new Attribute(
        get: fn ($v, $attr) => $attr['email'] === null,
    );
}

Now you can limit any functionality you want to keep from guest users.

On my front-end, I hide parts of the UI or show different messages to guest users depending on the isGuest attribute that I pass to the front end.

On my back-end I put specific checks in place to refuse certain functionality to guest users.

The implementation of this is now very straightforward and entirely up to you.

4. Encouraging registration

I tend toward being overly communicative to guest users (read: annoying).

I stick a big fat brightly-colored banner on every single page of the game that says "You're currently playing a Guest account. Click here to save your progress!". Clicking the banner takes them to the registration page.

You may opt to be a bit more subtle, or encourage guests to register after an initial tutorial.

This is where you might want to consider the marketing side of things a bit more. Do you want guests to convert to users no matter what? Do you prefer to discourage players from registering until they reach a certain point of the game? This is entirely up to you.

5. Guest Registration

Instead of creating a whole new user, we just want to convert the player's existing guest account into a fully-fledged account by having them give us a name, email and password.

In Trounced, clicking on the ~~annoying~~ persistent banner takes the guest to a registration page where we collect exactly that information from them via a form.

On the back-end, I validate this request and update the guest user. You could even throw in some additional rewards here if you wanted, as incentive to get guests to register their account.

// GuestLoginController

public function store(StoreGuestRequest $request): RedirectResponse
{
    Auth::user()->name = $request->get('name');
    Auth::user()->email = $request->get('email');
    Auth::user()->password = Hash::make($request->get('password'));
    Auth::user()->save();

    return redirect()->backToTheGame();
}

Then in my StoreGuestRequest, I make sure I'm getting all the required info and only allowing guests to hit this endpoint.

class StoreGuestRequest extends FormRequest
{
    public function authorize()
    {
        return Auth::user()->isGuest;
    }

    public function rules()
    {
        return [
            'name' => ['required', 'string', 'max:255'],
            'email' => ['required', 'email', 'max:255', Rule::unique('users')->ignore(Auth::id())],
            'password' => ['required', 'string', new Password, 'confirmed'],
        ];
    }
}

Now that your user has a valid email, the isGuest attribute will always return false and your game will function as normal. Full circle!

6. Cleaning up old Guest accounts

If someone comes and tries out your game but it's not for them, you might not want that Guest69420 user hanging out in your database forever.

In that case, we'll make the User model prunable, which is Laravel's built-in way of cleaning up old models.

We add the Prunable trait to the User model and then define a new prunable method to define the appropriate criteria. Check the documentation here, it describes all the setup.

In my case, any User models that still have a null email and were created 3 or more days ago should be deleted. Feel free to change the criteria, but remember that once a user loses authentication (such as session expiring) with your system, there's no way to re-authenticate them since there's no login information!

// User Model
public function prunable()
{
    return static::whereNull('email')
        ->where('created_at', '<', now()->subDays(3));
}

Now, in our app/Console/Kernel.php we'll register the command to prune the model regularly:

protected function schedule(Schedule $schedule)
{
    $schedule->command('model:prune', [
        '--model' => [User::class],
    ])->daily();
}

Be sure to also clean up any related models (such as inventories) so you don't have useless data floating around in the ether. This is typically best done in an observer, which is outside the scope of this post.

Now old Guest users are automatically cleaned up and thrown out of the database.

That's all, folks!

As with everything in programming, I'm sure there are other (better) ways to accomplish this same type of functionality. For me, I needed a simple way to get players in-game quickly without getting hung up on a registration form.

This bit of logic does exactly that, and it doesn't interfere with any other areas of my application or require me to write lots of abstract conditional logic.

Hopefully it can benefit you, too!

Designing a flexible and reusable quest structure for a browser game

Caleb Anthony — Mon, 08 Aug 2022 20:03:38 +0000

The quest system for Elethor is a flexible and powerful system, but it grew organically (read: morphed into a monster) over the months in an unfortunately ugly and difficult-to-maintain way.

Some of its pain points included difficulty adding more types of tasks to complete or rewards to hand out and having to design one-and-done quests that players will complete and never touch again (ouch).

I saw Trounced (my new kingdom-builder browser game) as an opportunity to take lessons learned and apply them to a new and improved system, complete with its own bugs and shortcomings!

This is the system that I ended up with, and I'm pretty happy with (so far).

Quest Design Criteria

Starting with any big hairy feature like quests, it's critical to sit down and define your parameters first. Luckily I had some experience (failures) with Elethor, so it wasn't too hard to put together a list.

1. Easily Extensible

I want to be able to add new quest types, rewards, and tasks easily. As the game grows, there will (and should) be more combinations of these things to create new quests.

2. Reusable & Schedulable

Instead of designing quests as a one-and-done experience (like most MMOs), I wanted to design them as repeatable events. So each quest needs to make sense as something that can be done over and over, as well as have a mechanism for easily starting, ending, and rescheduling.

3. Scalable

A noob might struggle to put together a straggling army of 100 soldiers while an established vet will be amassing thousands of elite units with little effort. Each quest task needs to be able to define its own criteria and rewards on a per-kingdom basis.

4. with a smattering of magic

There are always edge cases and alternate quest structures I'll want to handle. Adding some flexible magic into the quest system will let me handle some of these edge cases without keeping every quest as cookie-cutter as the last one.

You'll see.

Getting Started aka Database Schema

I tend to put as much data and configuration into the database as possible.

I don't know where I learned this habit, but as my games have grown in complexity, this has bitten me. I end up querying across 5-6 tables for some basic data that could (and should) have lived in a config file.

So this time I decided to overcorrect and opted to put most of the quest configuration and logic into classes.

This means I only ended up needing 2 tables. One for tracking each individual quest step (tied to an entity) and one for handling the scheduling of quests.

I added a bunch of comments to this schema so you can digest it as you go.

Schema::create('quests', function (Blueprint $table) {
    $table->id();
    // Quests belong to a realm for tracking hiscores
    $table->integer('realm_id');
    // Questable can be either a Kingdom, Alliance, or Realm
    // This is just a polymorphic relationship in Eloquent
    $table->integer('questable_id');
    $table->string('questable_type');
    // The collection of quests, e.g. "Daily" or "Rebuilding"
    $table->string('group');
    // The name of the specific quest step, like "Kill 300 enemy soldiers"
    $table->string('name');
    // An enum of possible tasks. This is a string because we want
    // to add more quest tasks later on without dealing with DB schema.
    $table->string('task');
    // Pretty self-explanatory...
    $table->integer('quantity_required');
    $table->integer('current_quantity')->default(0);
    // An array of reward objects.
    // Each reward is an item name, quantity, and rarity (for the UI)
    $table->jsonb('rewards');
    // An enum for how frequently the quest should reset (if at all)
    $table->string('reset_frequency')->nullable();
    // Pretty self-explanatory...
    $table->timestamp('started_at')->nullable();
    $table->timestamp('ended_at')->nullable();
    $table->timestamp('completed_at')->nullable();
    $table->timestamps();
});

For the quest scheduling, I wanted to keep all the quest groups and their start / end dates in the database. Then I have a queued job that runs daily to start / stop quests and run their custom start / stop logic.

Pretty self-explanatory. The quest_group has the same value as the group column in the above schema.

Schema::create('quest_schedules', function (Blueprint $table): void {
    $table->id();
    $table->integer('realm_id');
    $table->string('quest_group');
    $table->timestamp('started_at');
    $table->timestamp('ended_at');
    $table->timestamps();
});

Then I have models for each of these database tables and added relationships for all the polymorphic relations. That makes it easy to do something like $kingdom->quests and get all the quests for that specific kingdom.

Quest Groups

For each quest group, I have a dedicated class that handles the logic / setup / teardown.

Here's the abstract class that all quest groups extend:

abstract class QuestGroup
{
    public string $group;
    public string $description;

    // The meat of the class. Give the class an entity and then it builds out
    // all the steps of the quest for that specific entity.
    abstract public function buildFor(Alliance | Realm | Kingdom $questable): void;

    // Gets called by the scheduled job when it's time to
    // start this quest.
    abstract public function start(int $realmId): void;

    // Gets called by the scheduled job when the quest
    // is completed. Cleanup, hiscore rewards, rescheduling.
    // Most quests define when they want to start next and create a new
    // QuestSchedule object here, which creates a nice infinite loop of
    // scheduled quests over time.
    abstract public function end(int $realmId): void;
}

In the buildFor method, I get an entity (Kingdom, Alliance or Realm) and build all the steps of a quest against that entity.

This gives me flexibility to adjust the requirements for each step to the entity. Maybe a 10-kingdom alliance only has to attack 20 times, where a 50-person alliance should attack 50 times.

When starting a scheduled quest for an entire Realm, I often do something like this on the quest group class:

public function start(int $realmId): void
{
    Kingdom::where('realm_id', $realmId)
        ->cursor()
        ->each(function (Kingdom $kingdom): void {
            $this->buildFor($kingdom);
        });
}

I have a scheduled job that runs once a day and looks for quests that wanna start soon, then calls this start method on each group.

Then in the buildFor method, I dynamically build out each step.

For the following examples, we're going to be looking at a quest group named 'Claim to Vengeance' which rewards players for attacking one another and killing troops.

So how do I add tasks to this quest group that the player can complete?

Quest Tasks

Each task is an entry in the quests table that we made earlier.

An example from the Claim to Vengeance (CtV) quest looks like this. This is code in the buildFor method on the CtV group class, so we have access to the $kingdom variable.

Lots of comments just for you. :)

Quest::create([
    'realm_id' => $kingdom->realm_id,
    // Set the polymorphic relation details with the kingdom, since
    // we want this quest to be kingdom-specific. This could easily
    // be an alliance or realm if we wanted to do it that way instead.
    'questable_id' => $kingdom->id,
    'questable_type' => $kingdom->getMorphClass(),
    'group' => $this->group,
    'reset_frequency' => null,
    // We want the quest to start right now, and it will last for 3 days.
    'started_at' => now(),
    'ended_at' => now()->addDays(3),
    // We build the `$name` variable by calculating the kills required
    // for this kingdom based on their current acreage size.
    'name' => "Reach {$name}k points killing troops",
    // The task for this quest. I'll show you the tracker for this
    // specific task later on.
    'task' => QuestTask::TroopsKilled,
    // Dynamically calculated number of kills based on the
    // size of the kingdom.
    'quantity_required' => $killsRequired,
    // The rewards array is nested an extra "layer" deep
    // for reasons I'll explain down in the 'Meta' section.
    'rewards' => [
        [
            // Each `name` is exactly the name of an item in the database
            // which we look up when handing out rewards upon completion.
            ['name' => 'Hero Exp', 'qty' => 50, 'rarity' => 'Rare'],
            ['name' => '200 Soldiers', 'qty' => 1, 'rarity' => 'Uncommon'],
            ['name' => '50k Gold', 'qty' => 1, 'rarity' => 'Uncommon'],
        ],
    ],
]);

I utilized this logic to build out 6-7 steps for this quest, all with slightly different requirements, tasks, and rewards.

It's absolutely verbose (and I clean it up a bit in my actual class), but it lets me do whatever I want in code. Plus I can easily understand everything whenever I come back to check out this quest.

Which I like.

Quest Tracking

Now we have all our quest tasks built out, and a scheduler that can handle starting / stopping quests based on whatever criteria we want.

How do I handle actually tracking and updating the current_quantity for all these quests?

Quest trackers!

Each quest task enum has a corresponding tracker. I have abstracted almost all of this logic to a base class, so creating a new tracker is super easy.

Seriously, here's the tracker for the QuestTask::TroopsKilled enum you saw in the earlier quest task:

class TroopsKilledTracker extends BaseTaskTracker
{
    public function __construct()
    {
        $this->task = QuestTask::TroopsKilled;
        parent::__construct(...func_get_args());
    }
}

and then I just plop it in my code wherever I want.

Like so:

TroopsKilledTracker::dispatch($kingdom, $points);

The points are calculated based on the type of unit you kill. For example, soldiers (simple units) are only worth 1 point each, while elites (the strongest units) are worth 4 points each.

Here's another example of a dispatching a tracker that cares about how often you cast a certain spell. The second argument (quantity) defaults to 1, so we don't even have to add that here.

AlchemyCastTracker::dispatch($kingdom);

That's literally it.

Super simple.

But there's a ton of work in that BaseTaskTracker that we can uncover.

Brace yourself!

The ugly underbelly of task tracking

We'll break this down a little at a time.

First, you may have noticed that I didn't new up the tracker, I called the static dispatch method. This is a static method that returns the class constructor but gives me a Laravel-like API for creating trackers easily on the fly.

The real constructor looks like this.

public function __construct(Kingdom $kingdom, int $quantity = 1, ?string $group = null)
{
    if ($this->task === null) {
        throw new Exception("The QuestTask was not set on this Tracker.");
    }
    if ($this->task === QuestTask::Meta && $group === null) {
        throw new Exception("Meta tasks require a quest group to be set.");
    }

    $this->kingdom = $kingdom;
    $this->quantity = $quantity;
    $this->group = $group;

    $this->handle();
}

You'll recall that we can create task trackers for any entity (kingdoms, alliances, realms) but this constructor only accepts a kingdom.

That's because kingdoms are the only entities that can perform actions on their own. A player only ever controls a kingdom, and the alliance / realm tasks are automatically updated based on kingdom actions.

We do a bit of safety-checking at the start to make sure that all the parameters are properly set on the underlying tracker and then kick off the handle method.

public function handle(): void
{
    $quests = $this->validQuests();

    if ($this->group !== null) {
        $quests->where('group', $this->group);
    }

    if ($this->task === QuestTask::Meta) {
        $quest = Quest::where([
            ['task', QuestTask::Meta],
            ['group', $this->group],
        ])->first();

        (new QuestCompleter)->forMeta($this->kingdom, $quest, $this->quantity);
    }

    $quests->increment('current_quantity', $this->quantity);
}

This builds out a juicy query using Laravel's excellent query builder.

The validQuests method is 40 lines of nasty logic but basically makes these crucial checks:

Quests that aren't completed yet.
Quests that match the kingdom's ID, realm ID, or alliance ID.
Quests that have already started (or don't have a start date).
Quests that aren't ended yet (or don't have an end date).
Quests that match this task's tracker.
Quests where the quantity_required is -1 (unlimited) or still less than the quantity_required.

Quests don't always require a group to be set, as they can just be one-off tasks (like for new accounts). But if the group is set, we filter to only include quests that match the group provided.

If the task is a 'Meta' task, we add some extra logic. I'll go into those some more later, but essentially as you rack up points for meta quests, you automatically earn some bonus rewards.

Then we just increment the quest current_quantity by whatever the tracker said we should!

This structure is super flexible to allow me to:

Add more quest tasks with no problem.
Add more trackers super easily and throw them wherever I want in the code.

Brilliant!

Completing Quests

Once a quest has current_quantity >= quantity_required, it's completeable and no longer gets updated.

This just means on the front-end we pop a little button that the player can click to claim the rewards and update the completed_at timestamp.

If I wanted, later on I could also add a step before a quest closed or reset to automatically check all quests that could be completeable and auto-complete them for the player and hand out rewards.

I'm not doing that right now because half the fun of finishing quests is clicking 'Complete' and seeing all the juicy rewards flow into your inventory. If you automate your whole game away, there's nothing left for the players to do!

Plus seeing a bunch of completed quests is satisfying...

Meta Quests

Lots of games have collections of quests, and in that collection is a progress bar. This shows your overall progress through the whole quest line. As you progress through all the quests, you maybe even unlock rewards at certain points.

That's the purpose of a meta quest.

As an example, the Daily quest gives you a ton of tasks that you can do, and each task also rewards a small number of 'Meta Points'. This is a "magic" item as far as the code is concerned, which just increments the current_quantity on all quests in the same group with the Meta task.

When you reach certain breakpoints, you get a little chunk of rewards from that meta quest. This encourages players to be completionists, since you can give a bonus reward at the end of a quest line for completing every step.

You saw an earlier quest reward structure with an odd nested array. The reason is so we can accommodate the reward structure of a meta quest, which looks like this:

'rewards' => [
    25 => [
        ['name' => '2k Mana', 'qty' => 1, 'rarity' => 'Common'],
        ['name' => '20k Gold', 'qty' => 1, 'rarity' => 'Common'],
    ],
    50 => [
        ['name' => '20k Gold', 'qty' => 1, 'rarity' => 'Common'],
        ['name' => '5k Mana', 'qty' => 1, 'rarity' => 'Uncommon'],
    ],
    75 => [
        ['name' => '50k Gold', 'qty' => 1, 'rarity' => 'Uncommon'],
        ['name' => '200 Soldiers', 'qty' => 1, 'rarity' => 'Uncommon'],
        ['name' => '200 Acres', 'qty' => 1, 'rarity' => 'Rare'],
        ['name' => 'Hero Exp', 'qty' => 50, 'rarity' => 'Rare'],
    ],
    100 => [
        ['name' => 'Hero Exp', 'qty' => 100, 'rarity' => 'Rare'],
        ['name' => '50 Elites', 'qty' => 1, 'rarity' => 'Rare'],
        ['name' => 'Low Alchemy', 'qty' => 1, 'rarity' => 'Epic'],
        ['name' => 'Credit', 'qty' => 25, 'rarity' => 'Legendary'],
    ],
],

It's probably pretty self-explanatory. Once you break the 50 Meta Point breakpoint, you earn some gold and mana items.

On the front end, you get a nice little progress bar like this.

Oh, and because this quest is built specifically for each entity, you could change where those reward breakpoints are. Like letting kingdoms invest in a boost that makes it easier to achieve certain quest benchmarks, or power up certain rewards.

The possibilities are endless, and all contained neatly in that quest's group class.

BONUS: Flexible UI

The UI for almost all quest steps looks pretty much the same, but because of the flexibility of my back-end, I wanted some flexibility for the front-end too.

Here's an example of the 'Daily' quest vs the 'Sign-In' quest using the exact same back-end quest structure.

I wrote a slightly different component on the front-end for all quests that belong to the Sign-In group, and everything works beautifully!

The way the sign-in quest is set up is a bit different, but it uses the same exact system.

It's scheduled to reset once per month.
Each step has 0 quantity_required, making it immediately completeable.
Each step is scheduled to only be available for a 24h window.
Each step gives 1 Meta Point.
It utilizes a meta quest that gives super strong rewards for checking in 28 days during the month.

It's 100% using my existing quest system with no additional logic or special checks. But it functions differently from a player perspective.

This was a quest structure that I came up with after designing my quest system, and I was pleasantly surprised to see that it fit perfectly into my existing architecture.

That's always a sign you're on the right track!

Closing Thoughts

No system is perfect, and as this quest system rolls into production and ages like milk, I'm sure I'll be writing more posts about lessons learned.

However, the power and speed of development this system has already given me in creating new content is impressive.

I'm not often impressed by my own code!

Leveraging DTOs for JSON database columns as an alternative to additional tables

Caleb Anthony — Fri, 22 Apr 2022 22:07:21 +0000

Today I get to ramble a bit about a relatively new solution I've come up with for a problem that I'm sure a lot of you game developers have had before.

Here's the gist.

In Trounced (a simplistic kingdom builder game) players can have multiple kingdoms. Each kingdom then has its own land, armies, hero, alliances, and more. We're going to take a closer look specifically at land and armies.

In the original database design, land and armies were each their own tables with a foreign key to attach them to the kingdom.

Schema::create('lands', function (Blueprint $table) {
    $table->id();
    $table->unsignedInteger('kingdom_id');
    $table->foreign('kingdom_id')->references('id')->on('kingdoms');
    // Other stuff here
});

Then on the kingdom model, I could easily access them via a relationship.

// Models\Kingdom.php
public function land(): HasOne
{
    return $this->hasOne(Land::class);
}

public function army(): HasOne
{
    return $this->hasOne(Army::class);
}

However, there weren't any situations where I only fetched the individual army or land of a kingdom without also needing (or already having) the kingdom.

So I always ended up eager loading that data with the kingdom when I needed it.

// Always this
$kingdom = Kingdom::where('id', $kingdom_id)
    ->with('lands', 'armies')
    ->first();

// Never this
$land = Land::firstWhere('kingdom_id', $kingdom_id);

Now I'm pretty against premature optimization. But when it comes to game development I've learned (through painful experience) to be more prudent when it comes to infrastructure and database design. Some things are easier to change down the line than others.

So late one night as I couldn't sleep, I thought to myself "is it really necessary to query 3 tables to get this data, or could I just query 1?".

There has to be a better way.

I've been looking for an excuse to dabble in NoSQL for a bit now. While Trounced isn't the place for it, I figured this could be a chance to dip my toe in the schemaless pool.

So I decided to use JSONB columns (Postgres) on the kingdoms table with the lands and armies data. The result being now there's only one table to fetch and update all that data, which will result in improved performance as the game scales.

Consistent Structure

The biggest issue I've faced when it comes to using JSON columns is maintaining an expected structure.

While it's true that any arbitrary data can go in the column, you typically have certain parameters and validation to enforce. No one benefits when you throw data around willy-nilly.

I looked at a few options for putting data into JSON and while it's easy enough to validate on the way in, I also wanted to pull a predictable and usable structure (read: a class) out of the database.

Laravel already has the ability to cast specific fields on a model into an array or even a collection.

// Models\Kingdom.php
protected $casts = [
    'land' => 'array',
    'army' => 'array',
];

Which makes it easy to do things like:

// Adjusting the free land in a kingdom
$kingdom->land['free'] += 100;

// Fetching the free land in a kingdom
$freeLand = $kingdom->land['free'];

But this syntax is still a bit cumbersome.

There's no IDE autocompletion.

There's no validation.

And I'd prefer being able to access my properties with arrows all the way down rather than having to know where the array structure begins.

// Is it this...?
$freeLand = $kingdom->land->free;

// ...or this?
$freeLand = $kingdom->land['free'];

Not to mention validating deeply nested structures can easily becomes a tangle of conditional logic.

Data Transfer Objects...to the rescue!

Enter Data Transfer Objects, or DTOs.

If you aren't familiar, check out Martin Fowler's brief summary on them (and read a few of his other articles while you're there. Seriously, the man is a genius.)

I opted to use Spatie's DTO package and a bit of additional custom code for easy casting. I decided to map each JSON column to its own DTO, so I created two classes for land and for army.

On their own, DTOs aren't terribly useful. It's a lot of work to map your data and keep it up to date as your application changes. There's always a temptation to cheat the system for edge cases. Then all of a sudden your clean solution has turned against you and you wish you had just stuck to associative arrays.

So I decided to leverage Laravel's custom casts on my kingdom model to make it painful to take any shortcuts down the road.

// Models\Kingdom.php
protected $casts = [
    'land' => KingdomLand::class,
    'army' => KingdomArmy::class,
];

There's more behind the scenes (which we'll get into), but whenever I fetch a kingdom the JSON column of land is cast into the KingdomLand DTO. When I save the kingdom it translates that DTO into JSON before sticking it in the database.

Let's take a closer look, starting at the back and working our way forward.

1. Castable DTO

DTOs by default aren't castable the way Laravel expects. However, because Laravel supports custom casts, we can easily create a generic wrapper cast to use for all our DTOs.

This is the DTO Cast that implements Laravel's rules for creating a custom cast.

Loads of code ahead. Summary below.

namespace App\Infrastructure\Casts;

use Illuminate\Contracts\Database\Eloquent\CastsAttributes;

class DTOCast implements CastsAttributes
{
    protected string $class;

    /**
     * @param string $class The DataTransferObject class to cast to
     */
    public function __construct(string $class)
    {
        $this->class = $class;
    }

    /**
     * Cast the stored value to the configured DataTransferObject.
     */
    public function get($model, $key, $value, $attributes)
    {
        if (is_null($value)) {
            return;
        }

        if (is_array($value)) {
            return new $this->class($value);
        }

        return new $this->class(json_decode($value, true));
    }

    /**
     * Prepare the given value for storage.
     */
    public function set($model, $key, $value, $attributes)
    {
        if (is_null($value)) {
            return;
        }

        if (is_array($value)) {
            $value = new $this->class($value);
        }

        if (!$value instanceof $this->class) {
            throw new InvalidArgumentException("Value must be of type [$this->class], array, or null");
        }

        return json_encode($value->toArray());
    }
}

I want to pass any of my DTOs into this class and appropriately get the DTO or set JSON.

From there, I wanted to add a few more useful methods that'll get used in all the DTOs. This is the class instance that my DTOs will extend from, so I also make sure to extend from Spatie's DataTransferObject to get access to all those goodies.

namespace App\Infrastructure\Values;

use App\Infrastructure\Casts\DTOCast;
use Illuminate\Contracts\Database\Eloquent\Castable;
use Illuminate\Contracts\Support\Arrayable;
use Spatie\DataTransferObject\DataTransferObject;
use JsonSerializable;

abstract class CastableDTO extends DataTransferObject implements Castable, JsonSerializable, Arrayable
{
    public static function castUsing(array $arguments)
    {
        return new DTOCast(static::class);
    }

    public function toJson()
    {
        return json_encode($this->toArray());
    }

    public static function fromJson($json)
    {
        return new static(json_decode($json, true));
    }

    public function jsonSerialize()
    {
        return $this->toJson();
    }
}

This abstracts the generics so I can cleanly create my own castable DTOs with very little boilerplate.

The End Result

Here's what the KingdomLand DTO ends up looking like. Notice I'm extending from my CastableDTO I just created. This is what gets type-hinted in the $casts array on the kingdom model.

namespace App\Domain\Kingdom\Values;

use App\Infrastructure\Values\CastableDTO;

class KingdomLand extends CastableDTO
{
    public int $free = 0;
    public int $mines = 0;
    public int $forts = 0;
    public int $barracks = 0;
    public int $training_grounds = 0;
    public int $total = 0;
}

Clean.

Now, whenever I fetch a kingdom from the database, the land column automatically gets cast into this class. I can confidently interact with it before saving back to the database.

This makes it easy to validate each individual property. The Spatie package allows for custom validations as well, so the sky's the limit. Plus I can easily set default values for each property.

What if I wanted to add a new type of land structure later on? Easy, just add the property to the KingdomLand DTO with a good default and it's off to the races.

What are the bonuses of doing it this way?

IDE typehinting and autocompletion.
Validation.
Easily nested DTOs for more complex data structures.
Store all the data in a single JSON column, meaning fewer queries.

Plus you can also add your own custom methods to the class (making it a Value Object) to make your syntax more expressive.

class KingdomLand extends CastableDTO
{
    // public int $blabla...

    public function getMilitaryCount(): int
    {
        return $this->forts + $this->barracks + $this->training_grounds;
    }
}

// Simple and expressive
$kingdom->land->getMilitaryCount();

Is this the best place for those types of methods? I could probably be persuaded otherwise, but it is certainly an easy place to store logic and it's easy to work with.

The Downsides

Querying limited data from these JSON columns is a challenge I have yet to find a clean solution for.

For example, when searching for kingdoms to attack I only want to show the total acreage of a given kingdom. The attacker shouldn't know how much of the kingdom's land is designated to offense vs defense.

So to get this limited info, I have to query it like so.

$kingdom = Kingdom::select('name', 'land->>total as land_total', 'alert_level')
    // ->where...
    ->get();

Not very clean.

And now I also have to remember to access that data in a specific way.

// Works
$kingdom->land_total;

// Doesn't work
$kingdom->land->total;

Ick.

I could probably opt to grab the entire land column, cast it to my DTO, and then filter out the data I need, but that feels wasteful to ship data over the wire that is immediately thrown out.

Is there a better solution? Probably, and I've love to hear it if someone has it. But at least for now, the current DTO solution is miles ahead of the previous one.

The benefits and pitfalls of using Laravel to make a persistent browser-based game

Caleb Anthony — Wed, 13 Apr 2022 15:25:46 +0000

I can almost hear game devs screaming in my ear...

Why on earth would you encourage anyone to use a web framework to create a game? Don't you know there are game engines?

To which I would say....yeah! Game engines are great. They solve a lot of specific game-related development problems and make life as a game developer WAY easier.

Is your game super graphical? You might be better off with a game engine.

But if your game is more text-based, has limited graphical elements, or is primarily targeting the browser... a web framework might be the better choice for you.

You're nuts!

Probably. However, I've successfully released and run Elethor which is built entirely using Laravel. The process has honestly been a joy and I've become a better developer for it.

Not just a better game dev, but a better web dev too.

All that aside, if you're still not with me at this point, just skip down to the pitfalls section and have a gloat.

The Benefits

1. Scaffolding

Out of the box you get authentication, user sessions, validation, error handling, and a whole lot more.

No setup.

No configuration.

The amount of headache this removes is a huge benefit.

If your project is purely a learning experience and you want to re-invent the authentication wheel for the 808th time, be my guest.

But if your goal is to create and release a playable game, you don't want to be spending any more time than necessary on non-game stuff.

2. Community

Laravel is super popular and only getting more popular.

Pretty much any issue / error / question you have has been asked and answered already.

You won't be spending time digging through source code or knocking your head against cryptic documentation. Spend time building your game, not debugging your lack of understanding of how a certain feature should work.

The handful of issues that I've come across that haven't already been solved can usually be tackled by a quick walk through the issues on GitHub.

3. Queues & Horizon

A lot of games handle rapid, heavy calculations. Being able to offload this work to a secondary process is immensely helpful for keeping your game feeling snappy. Plus, combined with Laravel Echo and event broadcasting, you can handle a lot of your core logic asynchronously.

Horizon works by booting up several instances of your application, storing it in memory, and then processing individual bits of code on-demand. Because you aren't having to boot your application for every request, these processes are fast. Add in a few queue workers all working side-by-side on the same server (or across several servers!) and you have a computing powerhouse on your hands.

This is Elethor running on 24 processes spread across 2 servers.

As an example in Elethor, there is a lot going on in the Corporation (think guilds) logic. Let's take a player who has just left their corporation. A bunch of stuff happens automagically:

They have their corporation permissions revoked.
They leave the corporation chat.
They leave all active Corp Groups they are in for group content.
They are disqualified from any currently-running Corp Events.
They lose their existing Corp Buffs, and Corp Buffs are recalculated for remaining members.
They leave the corporation.
A log item gets added to the Corp letting everyone know when the player left.

If all of these things were calculated on the same request, the player would have to wait a non-trivial amount of time.

Instead, all these actions are dispatched as jobs on the Horizon queue. This means the code looks like this:

RevokePermissions::for(Auth::user());
LeaveCorpThread::for(Auth::user());
DisintegrateGroups::for(Auth::user());
DisintegrateCorpEvents::for(Auth::user());
DisintegrateBuffs::for(Auth::user());
Track::event('corpRoster')->viaCorp(Auth::user()->corporation)->withMessage(...);

Auth::user()->corporation()->dissociate();

Not only is this code incredibly expressive and easily readable, but each job is dispatched as an asynchronous process after the player has received a response.

Can you write this type of system on your own? Sure. But with Laravel it comes built in to the framework, which is a huge win.

4. Task Scheduling

Cron jobs are great for scheduling regular tasks, but they can make maintenance a bit more complicated. You aren't just editing your codebase, but also editing the cron file on your server. What if you have multiple servers?

Laravel lets you manage all those scheduled jobs with an expressive syntax in one central place in your code. It works by setting up a single cron job on the server that hits your code, and Laravel takes care of the rest.

Here is a small snippet of some of Elethor's scheduled jobs:

// Give players Mastery exp
$schedule->job(new Learn, 'default')->everyFiveMinutes();
// Recycle old Resource Nodes by refreshing them
$schedule->job(new CycleResourceNodes)->hourly();
// Removes expired market listings and returns items to players
$schedule->job(new RemoveOldListings)->daily();
// Gets a daily snapshot of some useful administrative statistics
$schedule->job(new TrackUsefulStats)->daily();

Or as a more robust example, here is how the Charitable Giving Corporation event gets automatically scheduled:

$schedule->call(fn () => (new CharitableGiving)->start())
    ->name('cg:start')
    ->weekly()
    ->tuesdays();

$schedule->call(fn () => (new CharitableGiving)->end())
    ->name('cg:end')
    ->weekly()
    ->sundays();

I don't even have to explain this code it's so expressive.

This is spread out across several servers and I don't have to worry about tasks being duplicated or getting dropped. Plus I can spin up another server with the same codebase and be off and running with a single cron entry.

Glorious.

5. Eloquent / Query Builder

Eloquent is Laravel's ORM. It provides a great syntax for fetching, manipulating, and extending your database models.

You don't have to write raw SQL in your application because Eloquent handles all that behind the scenes.

On the home page of Elethor, I fetch the latest announcements to show to players who are logging in.

News::orderBy('updated_at', 'desc')
    ->where('type', 'announcement')
    ->get();

Dead simple, and I'm off to the races.

But Eloquent isn't always the ideal tool for the job.

Now this one is a bit controversial because to be honest, Eloquent is sometimes heavy-handed, especially in game dev. There have been several situations where Eloquent technically gives me what I want but is much slower at getting it than writing my own SQL would be.

Which is where the Query Builder comes into play. I still don't have to write raw SQL in my game because I can just use the incredibly flexible query builder.

As an example, players in Elethor have several Companions. Companions are level-able NPCs that give a bunch of buffs. These Companions gain exp on a regular basis, so it needs to be lightweight to give this exp.

Using Eloquent, I could get this:

Companion::where('user_id', $this->userId)
    ->get()
    ->each(function (Companion $companion) {
        $companion->experience += $this->exp;
        $companion->save();
    });

This does exactly what I want, but it also fetches a lot of unnecessary data and hydrates each Companion model. That's overhead that I don't need and can't afford.

So instead I use the Query Builder.

DB::table('companions')
    ->where('user_id', $this->userId)
    ->increment('experience');

Now I'm not fetching anything from the database. I'm just updating the companions with a single SQL statement.

Now this has a few caveats (which is probably a whole blog post on its own) but having the option to use the expressive Laravel syntax without being forced into a bulky ORM is brilliant.

6. Notifications

This ties in great to game development. Laravel makes it dead easy to send notifications via Discord, Email, SMS or several dozen other options as well.

Has your player just reached a new level milestone?

Notification::send($user, new LevelMilestone($user->level));

Has their kingdom just been attacked?

Notification::send($attackedUser, new UnderAttack($kingdom));

Is there an event starting soon? You get the picture.

Write a single notification class (like a new event starting) and then identify all your channels on that one notification. Then easily pick and choose which channels the notification should go to on case-by-case basis.

It's so easy.

// UnderAttack.php
public function via($notifiable)
{
    return $notifiable->prefers_discord ? ['discord'] : ['mail', 'sms'];
}

Instead of having to set up your own integration, just use Laravel. Now you're back to writing the code you care about (which is your game code, if you were curious).

The Pitfalls

This whole section can partially be summed up in "Laravel isn't a game engine".

But you already knew that.

While Laravel is great at a lot, especially when it comes to building browser-based games, it has its own pitfalls as well.

1. Eloquent

A benefit and a pitfall? Yeah, but honestly I would still rule it as mostly a benefit. A benefit with caveats. A double-edged sword cuts both ways. I'll show you what I mean...

When it comes to game development there can be a lot of calculations happening in a short span of time. Involving lots of various models.

Being able to easily fetch models via Eloquent is a great tool. But if you're not careful you can end up with poorly performing code that is quite confusing.

The earlier Companions example is a great starting point:

Companion::where('user_id', $this->userId)
    ->get()
    ->each(function (Companion $companion) {
        $companion->experience += $this->exp;
        $companion->save();
    });

Once you get familiar with Eloquent, you quickly learn that ->get() is significant. It's the point where your records are fetched from the database.

There are a couple of other key words like this too, such as ->first() and ->all().

If you're not aware, you could accidentally do something like this:

Companion::all()
    ->where('user_id', $this->userId)
    ->each(...);

While this looks similar to the earlier code, it's critically different.

This example fetches every single Companion from the database.

Then it filters those models down to the ones you want.

With 20 players? No problem.

With 5,000? Fatal error: Out of memory (allocated...

When you run into these gradual slowdowns, it isn't immediately clear where the issue is. Even if you isolated the issue, it's not immediately clear what is wrong with that code.

Is that a fault of Eloquent itself? Not...necessarily.

But it absolutely qualifies as a pitfall.

2. Websockets

You can do native websockets with PHP, but it's not straightforward with Laravel. Laravel Echo helps handle the client-side of websockets, but you need to manage the server side on your own.

Initially, I used an intermediary NodeJS server, then switched to handling websockets natively in PHP, and am about to switch back to a NodeJS server.

Is this the fault of Laravel? Not necessarily. But if they had a clearer setup process and recommended (open-source) packages it would make this a bit less of a potential pitfall.

3. Request / Response

PHP is built around a request/response structure. Processes are short-lived and data isn't stored in memory between requests.

For the vast majority of web applications, this is great.

For game development, it can be less than ideal. A lot of games want to store certain data in memory and re-use it between requests.

Caching can help, but if your cache is on a different server you have to deal with network overhead.

Laravel has a solution for this called Octane that works on top of something like Swoole. This gives you concurrency, faster cache management, and some other goodies. But it has its own caveats.

It's a bit of a time investment to get something that other languages (or game engines) get out of the box.

Is it a reason to avoid Laravel altogether? Not in my opinion, but it is a potential pitfall to be aware of.

4. Realtime

This isn't a fault of Laravel as a framework, but more a shortcoming of PHP. PHP just wasn't designed to do realtime.

If your game is going to rely on realtime at all, it's probably best to find another tech to work with.

Right tool for the job, and all that.

Summary

I personally have been quite happy with my decision to use Laravel to create my games thus far.

Is it always the best solution? Obviously not.

But for the types of games I have made, it has been great and has helped me get up and running quickly.

Should you use Laravel for your next project? That's entirely up to you, but hopefully this article gave you a few tidbits to help make the best decision.