Ability FSM?

[andretchen0]

TL;DR

I'm considering making a few tests using a revamped ability architecture. A finite state machine (FSM) would make a suitable, flexible replacement to the current system.

---

I've been working on converting ability.js to ability.ts.

The module seems to have been coded for flexibility, but the result is that it's quite difficult to know when functions are called, where their definitions come from, what and how many arguments they're called with. There's a lot of reliance on arguments rather than named arguments. There's also a lot of reliance on ambiguous argument objects – e.g.

/**
 * @param {Object} opt Animation object to extend.
 * @return {void}
 */
animation2(opt) {

and

/**
 * @param {Array} hexes Array of hexes to test.
 * @param {Object} o
 * @return {boolean} At least one valid target?
 */
atLeastOneTarget(hexes, o) {

that have to be tested to see if they include a particular field.

This means that converting to TS isn't particularly useful in a lot of cases.

There's also quite a lot of indirection. Objects passed to functions extend other objects and are passed to still other functions to be extended.

Ability Finite State Machine (FSM)?

It seems to me that a lot of the indirection and ambiguity could be removed if abilities were implemented as an FSM – finite state machine. A first draft of a State could perhaps be implemented with an interface like this.

Mouse/Pointer events:

• onHexEnter(hex:Hex)
• onHexLeave(hex:Hex)
• onHexTap(hex:Hex)
• onCreatureEnter(creature:Creature)
• onCreatureLeave(creature:Creature)
• onCreatureTap(creature:Creature)
• onButtonEnter(button:Button)
• onButtonLeave(button:Button)
• onButtonTap(button:Button)
• onCancel()

Lifecycle events:

• onStart()
• onPause()
• onResume()

Properties:

• getHighlightedHexes()
• getDashedHexes()

An engine – perhaps in game – would

• be responsible for getting mouse/click/hover input to the top of the stack, letting it know how the user is interacting with the playfield
• ensuring that lifecycle events are called appropriately as states are pushed and popped from the stack
• making sure to inform hexes when if there's a visual change necessary following a state change or event
• canceling a move if other button presses interrupt it, e.g., starting but not finishing a move and then instead delaying the creature

Then the current state itself decides if requirements for a state transition are satisfied and what that transition should be – directly in the src/abilities/* file – rather than relying on a series of callbacks. If a state change is required, the current state could:

• create a new state – typed with unambiguous arguments – and push it to the stack; e.g., if the next state needs a Hex and a Creature instance, then the creator has to pass the Hex and Creature.
• pop itself off the stack – optionally sending back an argument.
• clear the stack – e.g., when cancelling the ability altogether or after finishing the ability.

In addition to centralizing an ability's core in its file and typing arguments, this has a concrete advantage over the current system that an FSM can have an arbitrary number of nodes, without requiring modification of calling code. If a new ability requires the user to select 2 hexes, then a creature, that's easy to implement simply by pushing new states.

Branching is also relatively trivial – e.g., a particular ability could allow a player to either:

• damage 1 enemy by clicking on it or
• place 2 traps by clicking on empty hexes

---

Thoughts welcome.

[DreadKnight]

There's #1469 open for a revamp, but I like your view/approach with a FSM, as it includes proper stuff to complement the issue.

The coder who wrote initial prototype proposed a rewrite for abilities back in the day but he was focusing on a modular approach regarding their effect, similar to a game with some game that featured 4 colored anime-ish looking color cloaked mages (but probably not Wizards of Legends¹), where you would create and evolve your magic spells using some modular as you pleased.
Problem is that in Ancient Beast, besides the basic attacks, I've designed the abilities to be as unique as possible², breaking the existing expectations and molds quite often, so the modularity aspect wasn't too good, but I see you've focused on the elementary tools needed by most of them, which is great, as that would surely get things to the next level, as abilities are a super important part of the core gameplay and we need to handle them properly and make them less scary, as many coders found them a scary mess.

Having interactions handled by an engine is great stuff, because eventually we'll need a MVC approach, so that we can easily decouple from current UI or graphic mode in order to have the game be able to easily embrace new hardware down the line or have different graphical modes / renderers - #1970 #2021 #249

¹ On that note (game with modular abilities), I've acquired and played Vampire Survivors lately quite a bit, there you can upgrade various attack parameters with some objects/skills, but even so, not all of them are cross-compatible, so you either need to test and observe or constantly dig through wikis, as the UI is not very informative about what works with what (could have been an easy fix overall) except with object/skill required by for a certain attack to evolve past its ultimate level, looking way different and becoming way more powerful.
I currently have no plans to make AB abilities to have certain parameters like range or area of effect upgradable, items were planned before and acted like current drops, improving certain stats, but I might consider ability upgrade options in order to add some customization and variation in order to make the game way more replayable and fun, allowing to counter certain units better or improve team synergies, also being able to come up with new strategies.
² Reference games like Dota2 also do this, though you would see the overall pattern of a hero's ability repeat in a more powerful version in another hero's ultimate and also some ability effects being reproduced by items.