Tricks of the Trade

Anatomy of an amiibo ID

2024-02-16T00:51:00+00:00

Intro

You may have heard about data miners finding game details and releasing them before the game is ready. One such thing is amiibo IDs. However, I’ve been guessing amiibo IDs long before data miners even found them. Often times a game has amiibo support added before the amiibo is released. Guessing the IDs is fun for unlocking new items and behavior before the amiibo figure is available.

With the release of Sora for Super Smash Bros. Ultimate, I’m going to reveal how I’ve been guessing the amiibo IDs. Once Nintendo finds this article, future IDs may be less guessable. Though this is a fun exercise in reverse engineering and knowing the process is enlightening.

DISCLAIMERS

The bulk of the data for this article came from AmiiboAPI with the rest coming from my own research.

I do not condone cloning amiibo and selling them as your own. Even though I unlock features early, I subsequently buy amiibo once they do become available.

Structure

The structure of amiibo IDs has been known for a long time. Here’s the ID for Zelda and Loftwing released with the remaster of The Legend of Zelda: Skyward Sword.

01010300 04140902

That’s the ID represented in hexadecimal form. Here are the parts broken out:

010: Game series = The Legend of Zelda

1: Character = Zelda

03: Variation = Zelda with Loftwing

00: Form = Figure

0414: Serial number = 414 hexadecimal 1044 decimal

09: amiibo series = The Legend of Zelda

02: Format version = 2

The first three bytes (010103) contain the key information for the character. The remaining five bytes (0004140902) contains metadata. Most games only look at the first two or three bytes. This allows them to be compatible with future amiibo without updating the game.

The rest of this post will dive into the details of each portion.

Game Series

Not to be confused with the “amiibo Series”. The game series represents where the character originated from, ex. Link -> The Legend of Zelda. For game series with many amiibo, there will be multiple game series IDs assigned. How this portion of the ID is more elusive and will be covered in detail later in the article.

Character and Variation

The character is the most important information in the amiibo ID. This is often the only information a game is concerned about.

For a single game series ID, there are 15 possible amiibo. Some series have much more than that. So when it exceeds 15, it add a new game series ID. The subsequent series ID is usually sequential. However, The Legend of Zelda series uses 010 but some Breath of the Wild figures use 014.

Speaking of The Legend of Zelda, here are some characters:

0 Link
1 Zelda
2 Ganondorf
3 Midna and Wolf Link
4 Daruk
5 Urbosa
6 Mipha
7 Revali

You might be thinking, where is the Sheik amiibo? This is where variation comes in. Zelda is variation 00. Sheik is variation 01 (25 year-old spoiler…Sheik is Zelda).

The variation is used to distinguish the “Player 2” figures. Specifically the Super Smash Bros. Cloud, Corrin, and Bayonetta figurines.

The variation has also been used to distinguish game-specific amiibo. For example, Zelda & Loftwing, Cat Peach, and Cat Mario are different variations from their base character. Scanning these amiibo into their respective games gave different rewards than scanning other variants.

The use of variants is not consistent. For example, shortly after the Skyward Sword and Super Mario 3D world remasters release came Metroid Dread. The Metroid Dread Samus amiibo gives different rewards than other Samus amiibo but it’s not a variant. This means that Metroid Dread must look at the full amiibo ID to distinguish this amiibo.

To further confuse matters, Toon Link is a variant of Link. However, there is no Young Link variant. Super Smash Bros. Ultimate treats “Link” and “Young Link” as different characters. So, the game must look at the full ID. This means if there is a new “Young Link” amiibo released, it will be treated as Link unless the game is updated.

Whoever made the Skylander amiibo completely ignored the variation and serial number. Hammer Slam Bowser and Dark Hammer Slam Bowser share the same ID. Same for Turbo Charge Donkey Kong and Dark Turbo Charge Donkey Kong.

Currently, the character with the most variations is Isabelle from Animal Crossing. She has three figures and seven cards wearing the following six outfits.

00 Summer
01 Winter
02 Kimono
03 Dress
04 Tropical
05 Sweater

Character ID

Though I treat game series, character, and variation as three different things they really get mashed into one thing: the character ID. Let’s take character ID for Pikachu: 191900. It can be helpful to think of the game series having four digits, in this case 1900. Then the character number is 19 hexadecimal or 25 decimal. Adding 1900 and 19 gives the base ID 1919. Append the variation 00 to get the full character ID of 191900.

Form

The form determines their physical representation. The options are few but Nintendo occassionally surprises us with new forms.

00 Figure
01 Card
02 Yarn
03 Band

You’ve likely seen the figures. They are the most common. You may have also seen cards such as the many Animal Crossing cards.

The other types are less common. With the Yoshi series came several figures crocheted from yarn. This is a reference to Yoshi’s Wooly World where Yoshi and others are made of yarn.

The newest form are wrist bands. You receive these at the Super Nintendo World theme parks. This is a clever way to introduce more people to the amiibo functionality within games.

Serial Number

By itself, the serial number is mundane. It’s simply a sequentially-assigned number. What’s more interesting is in what’s missing. There are several gaps. These gaps could indicate canceled amiibo. Or some card series carved out more numbers than needed. More on this below.

amiibo Series

Not to be confused with the “Game Series”. For amiibo figures, this determines the base the figure stands on. Each base has a slightly different design. The most notable difference between game series and amiibo series is the Super Smash Bros. series. It contains characters from a variety of games, ex. Legend of Zelda, Mega Man, Pikmin, Metroid.

These are the current series:

amiibo Series ID	Series Name
`00`	Super Smash Bros.
`01`	Super Mario
`02`	Chibi-Robo!
`03`	Yoshi
`04`	Splatoon
`05`	Animal Crossing
`06`	8-bit Mario
`07`	Skylanders
`09`	Legend Of Zelda
`0A`	Shovel Knight
`0B`	…
`0C`	Kirby
`0D`	Pokemon
`0E`	Mario Sports Superstars
`0F`	Monster Hunter
`10`	BoxBoy!
`11`	Pikmin
`12`	Fire Emblem
`13`	Metroid
`14`	Others
`15`	Mega Man
`16`	Diablo
`17`	Power Pros
`18`	Monster Hunter
`19`	Yu-Gi-Oh!
`1A`	…
`1B`	Xenoblade Chronicles
…	…
`FF`	Super Nintendo World

Format Version

The final byte is the “format version”. So far it’s always 02. If a new format is ever made, then this number could be different. It’s not likely, so just expect this to always be 02.

Game Series Assignment

Now to dig into the most critical data, the game series. For existing series, it’s trivial to look up the game series ID. But for new games, how can you guess the series ID?

The game series numbers are arbitrarily assigned. Fortunately, people (especially programmers) like organization. I’ve deduced some patterns through what I call “playing solitaire with the data”. Basically categorizing data and finding similarities.

I’ll start by dumping a large table of data then explain what it means.

Series ID	Name	Publisher/Developer
000-002	Super Mario Bros.	Nintendo
004	x
008	Yoshi	Nintendo
00C	Donky Kong	Nintendo
010	Legend of Zelda	Nintendo
014	Breath of the Wild	Nintendo
018-051	Animal Crossing	Nintendo
054	x
058	Star Fox	Nintendo
05C	Metroid	Nintendo
060	F-Zero	Nintendo
064	Pikmin	Nintendo
068	x
06C	Punch Out	Nintendo
070	Wii Fit	Nintendo
074	Kid Icarus	Nintendo
078	Classic Nintendo	Nintendo
07C	Mii	Nintendo
080	Splatoon	Nintendo
…	…	…
09C-09D	Mario Sports Superstars	Nintendo
…	…	…
0A4	ARMS	Nintendo
…	…	…
190-1D4	Pokémon	Nintendo/GameFreak
…	…	…
1F0	Kirby	Nintendo/HAL Labs
1F4	BoxBoy	Nintendo/HAL Labs
…	…	…
210	Fire Emblem	Nintendo
…	…	…
224	Xenoblade	Nintendo/Monolith Soft
228	Earthbound	Nintendo
22C	Chibi Robo	Nintendo
…	…	…
320	Sonic	Sega
324	Bayonetta	Sega/Platinum Games
328	x
32C	x
330	x
334	Pac-Man	Bandai Namco
338	Dark Souls	Bandai Nameco
33C	Tekken	Bandai Namco
340	x
344	x
348	Mega Man	Capcom
34C	Street Fighter	Capcom
350	Monster Hunter	Capcom
354	x
358	x
35C	Shovel Knight	Yacht Club Games
360	Final Fantasy	Square Enix
364	Dragon Quest	Square Enix
368	x
36C	x
370	x
374	Super Mario Cereal	Kellogs
378	Metal Gear Solid	Konami
37C	Castlevania	Konami
380	Jikkyou Powerful Pro Baseball	Konami
384	x
388	x
38C	Diablo	Blizzard
390	x
394	x
398	x
39C	x
3A0	Persona	Atlus/Sega
3A4	x
3A8	x
3AC	x
3B0	x
3B4	Banjo and Kazooie	Rare/Microsoft
3B8	x
3BC	x
3C0	x
3C4	x
3C8	Fatal Fury	SNK
3CC	x
3D0	x
3D4	x
3D8	x
3DC	Minecraft	Mojang/Microsoft
3E0	x
3E4	x
3E8	x
3EC	x
3F0	Kingdom Hearts	Disney/Square Enix
3F4	x
3F8	x
3FC	x
400	x

The series IDs 000-319 are reserved for Nintendo. They don’t appear to follow a distinct pattern. So I won’t say more about them.

320 and beyond are for third-party developers. Notice that I set up the table so that each entry ends with 0, 4, 8, or C (12 decimal). I call each entry a “slot”. One slot is can have 64 amiibo (ex. 3740-377F) ignoring variants. Smaller publishers (ex. Yacht Club Games, maker of Shovel Knight) are assigned a single slot. Larger publishers that make multiple games are given five slots. This is enough for 320 amiibo (ignoring variants) across five game series.

The latest amiibo, Sora from Kingdom Hearts, was assigned series ID 3F0. Following this pattern, if a new publisher released an amiibo, it’s series ID would be 404.

You might think this is a large waste of space slicing out five slots at a time. However, from 404 to FFC inclusive, there are 767 slots. That’s enough for 153 more major publishers. amiibo have been around for almost a decade. The numbers aren’t running out soon.

Possible Cancelations

The following tables show gaps in the serial numbers. There’s also some speculation about what might have used those numbers. At the time of writing, the latest serial number is 043E.

Range	Size	Speculation
`3B`	1	Possibly Chibi-Robo amiibo
`1D9`—`237`	95	Probably Animal Crossing cards, increase 405 to 500
`23C`	1	Maybe another Skylander or Pokémon
`2C3`—`2E0`	30	Probably more Mario Sports Superstars, increase 90 to 120
`31F`—`34A`	44	Probably Animal Crossing cards, increase 56 to 100
`351`	1	Probably a Toon LoZ amiibo (Ganondorf?)
`357`	1	Probably a BotW amiibo (Calamity Ganon?)
`39A`	1	Probably a Link’s Awakening amiibo (Marin?)
`3D8`—`40B`	52	Probably Animal Crossing cards, increase 48 to 100
`416`—`417`	2	Possibly Splatoon 3 or Tears of the Kingdom
`42F`	1	More Power-Up bands? (Link?)
`431`—`432`	2	More Power-Up bands? (Donkey Kong? Diddy Kong?)
`436`—`43C`	7	Maybe Splatoon 3 or Xenoblade but probably not

Conclusion

For just being eight bytes of data, there is a lot that can be inferred. It’s similar to how the periodic table of elements came about. Or the German tank problem. Next time you see a mess of data, see if you can tease out those little patterns.

Reverse Engineering Dampé’s Dungeon Adventure

2022-10-18T02:49:00+00:00

Intro

Dampé’s Dungeon Adventure is my favorite feature in the Link’s Awakening remake. Since the dungeons can be stored on an amiibo figurine, the data is available to be easily read from it. I’ve been meaning to decode that data. Now three years later I finally got to it. It took about a week to decode the data for this post. Most of that time was cataloging the 187 available chambers.

Dungeon Data

Like all games that store data to an amiibo, the game has 216 bytes available. Link’s Awakening more or less uses that full space. I will go through each of the significant portions of that data. My explanations will use hexadecimal format, meaning that values are base 16 using 0-9 and A-F.

Basic Info

The first four bytes are in the following format: 0x03XX0100. Three of the four bytes appear to always be the same. The XX portion changes depending on the challenge chosen. Dampé has 24 challenges numbered 0x00 to 0x17. There’s also a free-play mode which has the value 0x30. So, must dungeons you see on amiibo will probably start with 0x03300100.

The tutorial levels are mostly the same as the free-play mode. The main difference is that they may have some extra restrictions: no sword, limited hearts, or limited time. There are also chamber placement restrictions. Some chambers are placed by Dampé. In the chamber data, these locked chambers are indicated by a 0x0000 chamber value (more on this in a moment).

The next four bytes are a mystery. I haven’t decoded them yet. They remain constant for a dungeon arrangement. Changing the dungeon changes these bytes, even if the same chamber is placed in the same spot. It seems like a random ID or perhaps a salt to make cryptanalysis on the tamper protection harder. Any time these bytes change, the dungeon must be played through to save it to an amiibo.

Chamber Data

The next 128 bytes are the most interesting. This is the chamber data. A dungeon is an 8x8 grid (up to 64 chambers). Each chamber gets two bytes. The chambers are stored in row-major format, meaning all of the first row is stored. After that is the second row and so on.

Looking at the raw data, a chamber will look like this: 0x6201. Cells without a chamber are always 0xFFFF. The data is stored in little-endian format. Basically that means the least-significant byte is stored first. This can be more efficient for computers to work with but the bytes are backwards from how we would normally read them. So, let’s flip it around: 0x0162.

There are 4 hex digits. We’ll ignore the first digit for now. The latter three are the important bits that determine the room. In short, these three digits represent coordinates: dungeon, y-coordinate, and x-coordinate.

The dungeons are numbered 0x0 to 0xA. If you look at the catalog of chambers, you’ll notice dungeon 0x8 is not used. That is the Wind Fish’s egg. There are no chambers from that dungeon.

Now for a brief history lesson. The original release of Link’s Awakening had the Wind Fish’s Egg as the final dungeon. In Link’s Awakening DX (released on Game Boy Color, there was a new dungeon released: the Color Dungeon. This is dungeon 0x9. It is optional, though you can play through it fairly early in the game if you know where it is.

But wait, I said it goes to 0xA. What about that? Dungeon 0xA isn’t a dungeon. It’s a grab bag of extra chambers. They are mostly some mini-bosses from the mini-dungeons.

Now for the x-y coordinates. You’ll notice that the y-coordinate comes first though we typically use the x-coordinate first. Remember the chambers are stored in row-major order. The y-coordinate determines the row. Then the x-coordinate picks the chamber within that row.

The x-y coordinates are not coordinates in your dungeon. Rather they are the coordinates of the chamber in the original dungeon.

If these are coordinates, then what about dungeons with multiple floors? There are two dungeons with multiple floors: The Key Cavern with two floors and the Eagle’s Tower with “four” floors.

If you map out all the chambers for the Key Cavern, they look like this:

Doing the same for the Eagle’s Tower:

There’s an interesting thing to note about the Eagle’s Tower. The fourth floor is unreachable. You have to collapse the fourth floor into the third floor in order to reach it. In reality, you are probably traveling to and from the third and fourth floors. Internally, the game is probably re-mapping the stairs and doors after you break the pillars. It’s a similar trick to how the multiple floors works in the first place to make a three-dimensional dungeon into a two-dimensional dungeon (which is really just a one-dimensional list of chambers anyway).

The keen eye will notice these two dungeons still fit into an 8x8 grid. This means you could logically create a multi-floor dungeon yourself even though Dampé’s map will show it as a single floor.

There are a few chambers that don’t exist in the original dungeons. The primary chambers being where you can play one of the nightmares as if they were a mini-boss. If you check these coordinates against the dungeon maps, they point to a location with no chamber. Perhaps through modding or glitches you could get to these chambers in the original dungeons. Or maybe it’s just a convenient organization system. There are a few chambers that don’t perfectly match their original counterparts.

That was a long explanation of the coordinate system. As promised, back to the first hex digit. Dampé’s Dungeon Adventure lets you add “plus effects” to a chamber. This can alter it in some way such as doubling the enemies or randomly dropping bombs/hearts/rupees. Here are the values of each plus effect:

Effect	ID
No effect	0
Bombs	1
Rupees	2
Hearts	3
Wallmaster	4
Double enemies	5
Shadow Link	6

The Wallmaster and Shadow Link enemies are limited to one per dungeon. The other effects can be added multiple times. Though the double enemy modifier may only be used on chambers with enemies.

Since the numbers are continuous instead of powers of 2 (1, 2, 4, 8, …) naturally a chamber may only have one effect. They cannot stack.

Bookkeeping Data

After the chamber data are two names, each up to 32 bytes. The first name is the owner who created the dungeon. The second is the name of the best completion time. They are almost certainly the same name unless you pass the data to another account via amiibo.

Note that the names are from the Nintendo Switch account name, not the Link’s Awakening save file name.

The names are store in UTF-8 format. It’s a complicated format but here’s a brief explanation. A character (called a grapheme) can be made of one or more code points. A code point can be between 1-4 bytes. All the ASCII characters (think Roman letters, Arabic numerals, common symbols) all fit in one byte. Accented letters, other alphabets, less-common symbols are more than one byte.

Nintendo Switch account names are limited to 10 characters. Seeing that a single code point can be up to four bytes and graphemes can have more than one code point, it’s conceivable that you could overflow the 32-byte limit on these names. On the Nintendo Switch keyboard, I don’t think there are any characters you can type that is more than two-bytes long. So 32 bytes is plenty.

The next data field is the best completion time. It is a four-byte integer (little endian) measured in centiseconds. Yes, centiseconds. The game never shows more than two decimal points. So there’s no need to use a more standard unit like milliseconds. This make the value more compact.

Even though four bytes could store a larger value, the timer is capped at 59:59.99. I made a full 64-chamber dungeon, including every boss and mini-boss. I was able to complete that labyrinth well under the hour limit.

Note that you must first play through and beat a dungeon before you can save it to an amiibo. There will always be a completion time.

Equipment

The next four bytes (really just two) are also interesting. They contain all the equipment you have when you saved the dungeon. Since you can’t get a chamber until you’ve beaten the associated dungeon, you will always be able to beat it (barring any mods or sequence skips). This also ensures that someone else who plays the dungeon will be on the same footing as you. So they can’t get a faster completion time just by having better equipment.

The equipment is stored in a bit field. This means each binary digit determines the gear you have. 1 means you have it, 0 means you don’t.

Even though this is a little endian number, I’m going to treat it as big endian for simplicity. It seems to fit better treating it that way. Here are the values of each item. Some values are guessed because you have to beat two dungeons before Dampé lets you build your first dungeon.

Equipment	Value
Sword	1
Magic Powder	2
Roc’s Feather	4
Power Bracelet	8
Ocarina	16
Bottle from Ghost	32
Bottle from Fishing	64
Bottle from Dampé	128
Pegasus Boots	256
Shield	512
Bomb	1024
Bow	2048
Hookshot	4096
Boomerang	8192
Magic Rod	16,384
Shovel	32,768

The next four bytes work the same. I call these the enhancements. They change your equipment. For example, upgrading the Power Bracelet to Powerful Bracelet, having a fairy in a bottle, or learning a song on the ocarina.

Enhancement	Value
Fairy in bottle 1	1
Fairy in bottle 2	2
Fairy in bottle 3	4
Secret Medecine	8
Flippers	16
Ballad of the Wind Fish	32
Mango’s Mambo	64
Frog’s Song of Soul	128
Koholint Sword	256
Mirror Shield	512
Powerful Bracelet	1024
Double Magic Dust	2048
Double Bombs	4096
Double Arrows	8192
Red Mail	16,384
Blue Mail	32,768

The red and blue mail are mutually exclusive. Through modding you could give yourself both. Not sure how the game would handle that visually.

Tamper Protection

The final four bytes are a CRC. Basically it’s a value that can be used to verify the data hasn’t been tampered with. In order to modify the data on an amiibo, you would also need to update this value accordingly. Otherwise, the data will be rejected. Super Smash Bros. Ultimate has a similar CRC for its data. Though it puts the CRC as the first four bytes instead of the last four.

Missing Data

So what’s missing? The number of hearts you have are not recorded. So someone playing a shared dungeon could have more or less. This could give them an advantage to get a faster time but a good player won’t get hurt much anyway.

There are no time limits. That’s a feature strictly of a few Dampé challenges. Setting the dungeon type to one of those challenges might get you a time limit.

The challenges that don’t allow you a sword don’t actually change the equipment. That’s also a feature of the Dampé challenges. Though conceivable you could modify the equipment list to take away the sword and other equipment/enhancements.

There’s no way to name a dungeon. Your dungeon will automatically be named “Shrine/Cave/Maze/Labyrinth of [Name]”. The name is determined by the number of chambers in the dungeon.

Classification	Number of Chambers
Shrine	3-10
Cave	11-20
Maze	21-30
Labyrinth	31-64

No descriptions either. These are determined by the dungeon level. Only Dampé’s challenges have semi-meaningful descriptions.

There is no creation date (for dungeons you’ve made) or received date (for chambers you’ve received via amiibo). Both of those are stored in the game itself.

How stairs are connected are not in the data. Instead, they recalculated each time a chamber is placed. The stairs are shown in one of the four corners of the tile. The game then calculates the distance between every pair of stairs. It then sorts them by distance (ascending). When distance is equal, it sorts by row (ascending). When row is equal, it sorts by column (ascending). It then runs through the list and pairs up the stairs. Since it uses a greedy algorithm you can fabricate where all the stairs are close together but one or more pairings are far apart. This would not be a good algorithm to minimize digging tunnels. Though it can be used to draw a happy little tree.

The UI has seven distinct colors assigned in this order:

Green
Cyan
Magenta
Yellow
Red
Blue
Orange

Knowing that order, you can follow along with the screenshots above to confirm the algorithm works as described.

Resources

For full details of the chambers, check out the chamber catalog. It almost certainly contains errors or missing details. There is a lot to note for 187 chambers.

I also used HexFiend for viewing the files. It has a feature to use TCL scripts to parse out binary data. I’ve included my script below. Note that the amiibo data must first be decrypted for this binary template script to be useful.

Updates

20 Oct 2022: Added details about the stair-pairing algorithm.

Amiibo Personality Analysis

2022-05-01T13:02:00+00:00

Update

8 April 2023: I had ported the personality calculation to Elixir. However, it was a direct port. I’ve now rewritten the Elixir code to be more readable. I also converted the JSON data to TOML and included excerpts of this post in it. Many fields were renamed to clarify their intent. The code generator to convert the TOML file into Elixir code has been omitted to focus on the core algorithm.

Summary

A while back, Ske reverse-engineered the SSBU amiibo personality calculation. The calculation is fairly complicated and this article will explain it to a level others can understand.

Personality Calculation

Amiibo have 66 different attributes that define their behavior. 34 of those directly affect their personality.

The personalities are broken up into eight different branches:

def
agl
ofn
rsk
gen
ent
cau
dyn

Each branch lists attributes that add or subtract points. The number of points depends on the level of the attribute. Attributes vary from 0.0 to 1.0.

Here’s an example of the def branch.

If the amiibo’s offensive attribute is above 0.26, then the def score is decreased by 18 points. If the offensive attribute is above 0.76, then the def score is further decreased by 20 points.

If the amiibo’s grounded attribute is above 0.25, then the def score is increased by 18 points. If the grounded attribute is 0.76, then the def score is further increased by 18 points.

All the branches, except dyn, require an amiibo to either have or not have an attribute above a certain level. For example, the rsk branch must have appeal (taunt) above 0.25. The def branch must not have the offensive attribute above 0.26. If a branch does not meet this requirement, then an amiibo cannot have any personality in that branch.

Each of the branches has three personalities. The nominal personality is determined by the number of points scored for that branch. For example, if the ofn branch has over 235 points, then the personality is Offensive. If the score is over 180, then it’s Aggressive. If the score is over 100, then it’s Enthusiastic.

SSBU calculates the score for each of the branches. Whichever branch has the highest score wins. If no branch meets the minimum requirements, then an amiibo is defined as Normal. There’s also a special case. If an amiibo has attributes all equal to 0, then it it Normal.

Personalities

The following lists some of the requirements for each of the personalities. For the full details, see the raw data. For attribute details, see this guide. For a visual representation, check out this spreadsheet.

Normal

This personality is the least interesting. It’s the default if no other personality fits.

def (Cautious, Realistic, Unflappable)

Description

This personality must use its shield a lot and walk on the ground. It must not not do anything too aggresive like going off stage. It shouldn’t run and collecting items is too risky. Overall, this is a hard personality to get because many attributes subtract from it and not many add.

Must NOT have

offensive >= 0.26

Increased by

grounded
shield master
shield catch master

Decreased by

offensive
dash
cliffer
item throw to target
dragoon collector
smashball collector
special flagger

Personality Scores

Unflappable >= 240
Realistic >= 180
Cautious >= 100

agl (Light, Quick, Lightning Fast)

Description

This personality must move fast. It must be aggressive but not in the air. Collecting items is ok but anything that requires charging or would leave the amiibo in a vulnerable state is too risky.

Must have

dash >= 0.26

Increased by

offensive
dash
dash attacker
item collector
carrier broker

Decreased by

air offensive
smash holder
critical hitter
shield master
hammer collector
special flagger
homerun batter
club swinger
charger

Personality Scores

Lightning Fast >= 225
Quick >= 170
Light >= 100

ofn (Enthusiastic, Aggressive, Offensive)

Description

The amiibo must be aggressive and in the face of its opponents. Attacking off stage is encouraged. Items should not be used. If they are picked up, then they should be thrown at an opponent immediately.

Must have

near >= 0.25

Increased by

near
offensive
attack out cliff
dash
air offensive
dash attacker
meteor master
item throw to target

Decreased by

feint shooter
item collector
dragoon collector
smashball collector
hammer collector
special flagger

Personality Scores

Offensive >= 235
Aggressive >= 180
Enthusiastic >= 100

rsk (Reckless, Thrill Seeker, Daredevil)

Description

The amiibo must play aggresively off stage, especially dunking. The amiibo should be in the air a lot, preferrable off stage. Melee counter attacks and parries are encouraged but projectile counters are not. Going for risky items is encouraged.

Must have

attack out cliff >= 0.26

Increased by

near
offensive
attack out cliff
air offensive
cliffer
feint master
feint counter
dash attacker
critical hitter
meteor masher
just shield master
hammer collector
special flagger
carrier broker

Decreased by

grounded
feint shooter

Personality Scores

Daredevil >= 220
Thrill Seeker >= 160
Reckless >= 80

gen (Versatile, Tricky, Technician)

Description

This personality must parry. It will show off its skills including countering, parrying, dunking, and using most items.

Must have

just shield master >= 0.26

Increased by

attack out cliff
feint master
feint counter
feint shooter
catcher
attack cancel
meteor masher
shield master
just shield master
shield catch master
item collector
item throw to target
dragoon collector
smashball collector
item swinger
homerun batter
club swinger
dash swinger
item shooter

Decreased by

air offensive
carrier broker

Personality Scores

Technician >= 150
Tricky >= 120
Versatile >= 80

ent (Show-Off, Flashy, Entertainer)

Description

This personality must taunt a lot. Dunking, charging regular/smash attacks, and parrying are encouraged. Items should be used as intended and not just thrown.

Must have

appeal >= 0.25

Increased by

attack out cliff
smash holder
critical hitter
meteor masher
just shield master
dragoon collector
smashball collector
hammer collector
special flagger
homerun batter
club swinger
death swinger
charger
appeal

Decreased by

100 keeper
item throw to target

Personality Scores

Entertainer >= 230
Flashy >= 170
Show-Off >= 90

cau (Cool, Logical, Sly)

Description

This personlity must not parry. The amiibo should stay on the ground and use its shield a lot. It should stay far away from its opponents and counter projectiles if necessary. This is also a hard personality to get since many attributes take away from it and not many add to it.

Must NOT have

shield master >= 0.26

Increased by

grounded
feint master
feint shooter

Decreased by

near
offensive
attack out cliff
dash
air offensive
cliffer
feint counter
smash holder
dash attacker
critical hitter
meteor master
shield master
just shield master
hammer collector
special flagger
charger

Personality Scores

Sly >= 215
Logical >= 160
Cool >= 80

dyn (Laid Back, Wild, Lively)

Description

This personality is quite different from the others. It has no specific attribute requirement. It’s similar to rsk except it doesn’t counter or parry. It should attack a lot, especially off stage. Charging attacks is good. Holding items is strongly encouraged. What’s particularly unusual is it’s discouraged from throwing, swinging, or shooting items. This personality will simply hold items and never use them, except some of the risky weapons.

Must have

(Nothing)

Increased by

offensive
attack out cliff
air offensive
smash holder
dash attacker
critical hitter
meteor master
shield master
dragoon collector
smashball collector
hammer collector
special flagger
homerun batter
club swinger
death swinger
carrier broker
charger

Decreased by

catcher
attack cancel
just shield master
item throw to target
item swinger
item shooter

Personality Scores

Lively >= 210
Wild >= 160
Laid Back >= 80

The Best Starter Part 2

2021-04-14T01:34:00+00:00

Stats

As a follow-up to my previous post, I ran my Pokémon Trainers to 100 matches each. It took seven weeks to go from 50 to 100. Here are the following results:

I recorded each figure’s stats when Terry, Byleth, and Banjo & Kazooie were released just in case the update and rush of new figures skewed the results. Offhand, there appears to be little difference from the change. Most had their match count in the 80s. Squirtle had already reached 100 at that point.

I also recorded some notable high points. My Ivysaur topped out at a 29.27 rating. My only other amiibo with a higher rating is my King K. Rool at 30.86 after 50 matches. That’s impressive for a Pokémon Trainer. A large reason for the high rating appears to be that it often wins against three of the top amiibo: Incineroar, Bowser, and King K. Rool.

Analysis

My Pokémon Trainer (PT) Squirtle caught up with my Squirtle. Both Ivysaur figures kept a similar win rate and increased the rating by more than one full point. My Charizard was previously the top-rated of the six. It dropped by more than a full point. This brought it closer but still a full rating point above my PT Charizard.

The two Ivysaur clearly performed the best by a good margin. The two Charizard placed very differently. Splice’s nickname “Gamble Dragon” is fitting. The Squirtle were quite consistent but generally lower than the others fulfilling it’s nickname “Danger Turtle.”

If you want the best starter, then Ivysaur is the way to go. Perhaps it should be dubbed the “Cabbage Smasher.”

The Best Starter

2021-02-23T02:16:00+00:00

Ever since 1996 the question has been posed, “Which Pokémon is the best starter?” Super Smash Bros. Ultimate pushes this further. The Pokémon Trainer character allows choosing Squirtle, Ivysaur, and Charizard as the first Pokémon to come out. For Pokémon Day this year I wanted to find out which of the three starters work best for an amiibo.

Hypothesis

The general suggestion for Pokémon Trainer is to choose Ivysaur as the starter. The reasoning is that it takes two switches to get to Squirtle, who is the weakest of the three. Though in a three-stock match, Squirtle will likely come out three times. So it will inevitably come out.

Squirtle is light and fast. It’s good at getting in some damage but not so much at finishing. Ivysaur hits hard but is a bit slow. It also has poor recovery. But it will switch to Charizard to help recover. Charizard is the strongest of the three with great recovery and a several kill moves, especially, flare blitz. Though Charizard can easily flare blitz off the edge to self destruct.

My hypothesis is that Squirtle is the best starter. It gets in some quick damage while it’s fresh and unlikely to get knocked out. It then switches to Ivysaur to rack up some more damage. Once it gets knocked off the stage it will switch to Charizard which will then finish the job. At that point Charizard will likely have high damage and get knocked out, switching back to Squirtle and repeating the process.

Procedure

For this experiment I trained a Squirtle amiibo that performs well. I trained one following the Exion Vault guide. I specifically did not train it to switch, relying on the built-in AI for switching. This amiibo was able to take out an Incineroar. It has since taken out several Incineroar, King K. Rool, and Bowser.

Once I had a good performing amiibo, I spoofed it to be an Ivysaur and Charizard. These three amiibo start as their respective figures. There’s also a Pokémon Trainer amiibo that can explicitly choose its starter. I made three variations of that amiibo for good measure. These six amiibo are byte-for-byte identical except for the following:

Amiibo ID
Serial Number
Starter (for Pokémon Trainer)
Name (for Pokémon Trainer)
Checksums

I then put the amiibo on Amiibots and let them compete until they reached 50 matches.

Results

Here are the rankings after 50 matches ordered by ranking:

#1 Charizard

#2 Ivysaur

#3 Pokémon Trainer Ivysaur

#4 Pokémon Trainer Charizard

#5 Squirtle

#6 Pokémon Trainer Squirtle

Analysis

The scores alone don’t tell the full story. From what I’ve seen, Ivysaur is the clear winner with Charizard in a very close second. Both my Ivysaur performed very well. It wasn’t until nearing 50 that they started dropping off. For example, here’s a ranking at 20 matches:

Ivysuar was very close to a 29 ranking many times. Charizard got close a couple times too. The difference likely comes from changes in the amiibo pool. It also seemed to perform less well on Amiibots Zebes, but I haven’t done a thorough analysis on that.

My hypothesis turned out to be mostly right. My Squirtle played out as I expected. However, some times it stayed as a Squirtle far too long. I haven’t quite figured out what triggers Pokémon Trainer to switch (more ideas on that later). Squirtle did well as long as it followed the cadence. If it stayed Squirtle too long then it would get knocked out late in the Ivysuar phase or early Charizard phase. If the switching can be better controlled, then Squirtle becomes more viable.

For Ivysaur, it would do some good damage then get knocked off the stage. That would trigger the switch to Charizard. The opponent wasn’t always ready for a KO yet. So Charizard would rack up some more damage and finish. By that point Charizard was fairly damaged, especially from excessive use of flare blitz. If timing went well, it would switch to Squirtle which would be easily knocked out with the high damage. From there, the cycle repeated.

Charizard is an interesting case. It would often throw away the first of its three stocks. It would use flare blitz too early, causing it to hurt itself early on. The opponent often wasn’t in kill range yet then it would switch to Squirtle. This lead to the worse case scenario for Squirtle: trying to get a kill while it is heavily damaged. It would typically get knocked out. It would then respawn as Ivysaur. From here it played out similarly to the Ivysaur starter described above. With the opponent heavily damaged at this point it was in a strong position to quickly even the stocks.

In general, Pokémon Trainer appears to be a strong counter against Incineroar, Bowser, and King K. Rool. Those characters may be heavy and hit hard, but they are also big, slow targets. Instead of dodging or shielding, they often rely on their weight to take a blow then hit back harder. Charizard exploits this by rushing in with a powerful flare blitz, finishing them before they can react.

On the other hand, Pokémon Trainer struggles with smaller, lighter characters like Pichu, Sheik, and Falco. They tend to jump, shield, and dodge more. Many times I’ve seen Charizard flare blitz past an opponent and barely being unable to recover.

There is a very stark difference between my Squirtle amiibo and the Pokémon Trainer equivalent. Seeing they are almost identical in every way, they should perform the same. Yet, the two amiibo acted very differently. The Pokémon Trainer variant Squirtle would flare blitz of the stage. It would come back and grab the ledge. It would then jump and flare blitz soaring over the opponent’s head and off the other side of the stage. It would repeat this back and forth across the stage. All the while the opponent just stands there dumbfounded that this Charizard is inflicting self-damage.

The other five amiibo almost never behaved this way. Here’s a clip:

I have two hypotheses about this behavior:

Different behavior based on amiibo ID.
RNG is seeded based on bytes in the bin file, such as name.

Neither is a strong hypothesis but would be interesting to study further. For example, train a Link amiibo and spoof it for all the different figure variations. Or create several amiibo that are identical except in name (and maybe serial number).

Pokémon Switching

It’s very clear the amiibo switches from Ivysaur to Charizard when knocked off stage. Other cases are less clear. A time-based switch seems logical. Though there are times it changes very quickly and other times it stays for an unusually long time.

I’ve noticed Pokémon Trainer frequently switches when the Pokémon gets knocked high in the air near the blast zone. It’s the most reliable indicator I’ve seen anyway.

I suspect aerial switching may be related to the double-jump behavior jozz noted recentely. Basically jozz noticed that amiibo often will use an aerial jump when you walk under them while they are in the air. This double-jump behavior could trigger something similar to the recovery behavior. An aerial jump won’t save the amiibo since it’s near the blast zone. Instead, it tries switching to see if that gives it a better opportunity. More research is required for this behavior.

Caveats

This is just one instance of an amiibo. Other training methods will perform differently. When training this amiibo, I did not manually switch Pokémon. Teaching a Squirtle amiibo to manually switch may improve it’s performance since it will be less likely to stay a Squirtle for long periods.

If it’s true that amiibo act differently on different Switches based on how players have played against the AI, then manually switching amiibo may help the amiibo perform more consistently across devices.

Another caveat is the Amiibots matches aren’t entirely random. The composition of the pool changes over time. Also, the loyalty points allow for some trainers to be picked more frequently. Hopefully that means my amiibo were more likely to play against well-trained amiibo.

Conclusion

Pokémon Trainer is a very interesting and powerful character but is susceptible to RNG. Overall, Ivysaur and Charizard are the best choices but Squirtle can perform well too. I look forward to trying more variations with this amiibo.

Amiibo Easter Egg

2020-10-12T23:58:00+00:00

While delving down into the bits of Amiibo, I found what I believe is an Easter egg in the Amiibo.

Hexadecimal

Before I go further I need to explain different number systems. If you are already familiar with hexadecimal, then feel free to skip this section.

Typically we work in decimal (base 10). This is likely because we have 10 fingers. There are other number systems frequently used. Computers work in binary (base 2). Effectively all 0s or 1s. Long strings of 0s and 1s are hard to read. By converting binary to hexadecimal (base 16), we can make it more manageable. Hexadecimal uses 0-9 and A-F. This changes one byte from eight binary characters to two hexadecimal characters. To distinguish hexadecimal numbers from decimal numbers, they are often prefixed with 0x, ex. 0x1234.

Amiibo Character Numbers

Every Amiibo contains eight bytes that identify what character the figurine, card, or plush represents. For the purposes of this post, I’m going to focus on the first two bytes (16 bits).

The first 12 bits indicate the game series, ex. Super Mario Bros. and Legend of Zelda. The remaining four bits determine the character. Together these 16 bits are typically the same for Amiibo of the same character. For example, Link’s Awakening Link and Majora’s Mask Link share the same 16 bits (0x0100). The remaining 6 bytes (48 bits) differentiate them from each other.

Pokémon Character Numbers

Typically, the character numbers are assigned sequentially. For example, the Super Mario Bros. series starts with 0x000 to 0x002. The first several characters look like this:

Character	Number
Mario	`0x0000`
Luigi	`0x0001`
Peach	`0x0002`
Yoshi	`0x0003`
Rosalina and Luma	`0x0004`
Bowser	`0x0005`
Bowser Jr.	`0x0006`
Wario	`0x0007`
Donkey Kong	`0x0008`
Diddy Kong	`0x0009`

The Pokémon series doesn’t follow that pattern. Let’s look at a few of them:

Character	Number
Ivysaur	`0x1902`
Charizard	`0x1906`
Squirtle	`0x1907`

2, 6, and 7 are not sequential but any longtime Pokémon fan will recognize them. They are the national Pokédex numbers for those Pokémon.

Let’s look at the other Pokémon and subtract 0x1900 from each of their numbers.

Character	Number	Number - `0x1900`	National Pokédex
Ivysaur	`0x1902`	2	2
Charizard	`0x1906`	6	6
Squirtle	`0x1907`	7	7
Pikachu	`0x1919`	25	25
Jigglypuff	`0x1927`	39	39
Mewtwo	`0x1996`	150	150
Pichu	`0x19AC`	172	172
Lucario	`0x1AC0`	448	448
Greninja	`0x1B92`	658	658
Incineroar	`0x1BD7`	727	727

It’s a perfect match.

You may claim this is just careful organizing, not an Easter egg. It probably is. Though it’s a lot of wasted assignable numbers for Pokémon that haven’t been released. The only good reason I can see to do this would be if Nintendo released a large number of Pokémon Amiibo. This could be done through cards like the Animal Crossing cards. It would be interesting to see Pokémon TCG cards scannable as Amiibo.

One More Thing

Here’s the thing that really caught my attention. Does 0x1900 have any significance? Look through the character numbers again and one might stand out. Mewtwo’s character number is 0x1996. Any longtime Pokémon fan will recognize that number. 1996 is the year Pokémon Red, Green, and Blue released in Japan. This could be complete coincidence, especially with it being Mewtwo of all Pokémon. Still it’s too good to ignore.

Wait, What About Pokémon Trainer?

Actually, there are three Amiibo I haven’t mentioned: Pokémon Trainer, Shadow Mewtwo, and Detective Pikachu. They don’t fit the convention of the other Amiibo.

Personally I would have assigned Pokémon Trainer the number 0x1900. That would avoid interfering with Pokédex numbers. Instead Nintendo assigned him the number 0x1D40. Subtracting 0x1900 gives 0x440 or 1088. I don’t see any significance to those numbers. At the time of this writing, the highest national Pokédex number is Zarude at 893. Give it a few years and we may have a conflict on this number.

The Shadow Mewtwo card and Detective Pikachu figurine are particularly unusual. Nintendo assigned them the numbers 0x1D00 and 0x1D01, respectively. Typically Nintendo assigns the same character number to different Amiibo even if they come from different Amiibo series. For example, the Hammer Slam Bowser figurine from the Skylanders SuperChargers series has the character number 0x005 matching the Bowser and Wedding Bowser figurines from the Super Mario Bros. series.

Another oddity is that Shadow Mewtwo and Detective Pikachu don’t work as trainable Amiibo in Super Smash Bros. Ultimate. Scanning Shadow Mewtwo disappointingly does nothing and Detective Pikachu gives you a spirit as consolation.

Calculating 0x1D00 - 0x1900 gives 1024. Detective Pikachu is one later at 1025. These are also outside the current national Pokédex. Any programmer will quickly notice that 1024 is a power of 2 (2^10). Outside of that I see no significance.

Conclusion

This post is already longer than I anticipated. I hope you enjoy this fun discovery hidden in the depths of Amiibo.

Amiibo Personality Research

2020-09-13T18:41:00+00:00

Summary

Amiibo work by randomly selecting moves. By emphasizing effective moves and punishing ineffective moves, we influence the probability distributions of which moves are chosen. As said in The Hunger Games the phrase “May the odds be ever in your favor” is aptly applicable to Amiibo. We can’t make a perfect Amiibo but we can push the odds as far in our favor as possible.

An Amiibo’s behavior is defined by two parts: move set and personality. When asked about personalities, the immediate responses are often “personality doesn’t matter” or “you can win with any personality.” The reasoning: how ever you train an Amiibo a suitable personality will follow. This is a very pragmatic approach. But what about an empirical approach?

The question remains is this really the best way to find a personality? Or is it a local maximum? There are several personalities that are hard to get without spirits so they are rarely seen. Could we push the odds 10% (or even 1%) in our favor by choosing a different personality?

Procedure

To better understand how personalities work, I devised the following experiment. It’s designed to limit as many variables as possible.

Create 8 Amiibo of the same character.
Reset each Amiibo.
Use spirits to create each of the personalities (ignoring Normal).
Scrub the Amiibo of any spirit stats (type, attack, defense).
Disable learning.
Copy the move set from a known, good Amiibo into each Amiibo.
Play each of the personalities against each other on Final Destination in a first to 5 wins match with three stocks.
Collect the stats.
Back out to the menu between matches to ensure any learning is cleared.

You’ll notice I only created 8 Amiibo instead of 24 or 25. This is due to two things. First, without an Amiibots-like automated setup, running lots of matches is not reasonable. Having 24 Amiibo play each other would result in 276 matches. Using 8 only requires 28 matches, roughly a 90% reduction.

Second, the personalities are related. This flowchart from ArklaineGenesis shows how spirits can be used to change to different personalities.

Though when I ran through the process myself, I found an error. I was unable to get Thrill Seeker from Enthusiastic. I was able to get Thrill Seeker from Reckless. That leads me to believe the main personality branches look like this:

It has a nice symmetry to it. There are eight personalities with three different variations. As an aside, each character conveniently has three different skins. This made it easier to identify the Amiibo I created, along with naming them with the personalities.

It’s simple to confirm these branches. If you start with a fresh Amiibo, look for a spirit that moves it from Normal to the first stage of a branch. If you give the Amiibo three of these spirits total, you should end up with the final stage of the branch.

For this experiment I chose the 8 final stage personalities:

Daredevil
Entertainer
Lightning Fast
Lively
Offensive
Sly
Technician
Unflappable

These personalities should be the most distinct.

As for the character, I chose Link for several reasons:

Link is my main and I know him best.
He is a high-tier Amiibo and one of the most common in tournaments.
I have trained a Link Amiibo that performs decently.
Link has a wide range of attacks: grounded/aerial and melee/range with lots of kill options. He even has items. Any personality should find a home with Link.

There are some caveats with this experiment.

Different move sets may work better with different personalities.
Different Amiibo may work better with different personalities.
These matches were Link vs. Link. Other personalities may work better against different characters.
Theses were vanilla matches. Spirits could change the results.
Even with first to five wins there weren’t many rounds run.
The final stage personalities may be so specialized they aren’t as effective. The first or second stage personalities may be more balanced.
Personality labels are not granular. There are many underlying stats, ex. Aggression, Defensiveness, Edgeguard, Anticipation, and many more. Several of those are two bytes each. That gives over 65,000 possible values for each stat. Even within one personality there is a lot of variation.
This means giving different spirits likely would have given slightly different personalities.

Analysis

Enough about the procedure. Let’s look at the results.

For each match I recorded wins/loses, KOs/falls, and damage given/received. From that I derived several key metrics.

The full data set is here.

Match Wins

How many first-to-five matches the personality won.

Win Rate

Matches won to total games.

Damage Given Per Game

Average damage per game.

Damage Given Per KO

Average damage a personality did to get kill. Lower is better. This metric may be more important than damager per game. This means a personality can get kills sooner.

Damage Received Per Fall

Average damage before dying. Higher is better. Shows how long a personality can survive.

Surprisingly, the more aggressive personalities survived longest.

KOs Per Game

Average number of kills per game. For a three-stock game, closer to 3 is best.

KOs Per Fall

Number of kills per own death. Greater than 1 is good.

Conclusion

The Offensive personality is a clear winner with Lightning Fast in a close second. Offensive is top is every metric except one. Lightning Fast was able to kill at a slightly lower damage on average.

Sly only won a single game. It played too safely and just wasn’t able to get reliable kills. These personalities show the best defense is a good offense.

Clearly personality does matter. Most people I’ve talked to end up with an Enthusiastic personality. With Enthusiastic in the Offensive branch, they are already in a good position. This could explain the sentiment that personality doesn’t matter. If you always end up with a personality optimized for kills then you can focus more on tuning an Amiibo’s move set. Again, it’s a very pragmatic strategy.

This research would not have been possible without all the modders out there, especially fudgepop01. Thank you for your contributions to the Amiibo community.

Building Blocks: Agent

2018-09-01T03:24:00+00:00

I’ve long been an advocate of simple building blocks that are trivial to understand and implement. Despite their small size, they enable simpler development. Many that I have written are published on my GitHub account. Today I want to share my most used building block: Agent.

Agent comes from Elixir’s module of the same name. It is a thread-safe encapsulation around arbitrary state. Since I use Agent all the time in Elixir, I found myself wanting for it in other languages.

So, let’s implement an agent in Swift. Here is the basic type definition and constructor.

import Foundation

public final class SimpleAgent<State> {
    private var state: State
    private let queue: DispatchQueue

    public init(state: State) {
        self.state = state
        self.queue = DispatchQueue(label: "pro.tricksofthetrade.SimpleAgent", qos: .userInitiated)
    }
}

We can see that SimpleAgent holds some generic state. It also has a DispatchQueue. This is where the thread safety comes in. I’m going to assume you are familiar enough with Grand Central Dispatch (GCD).

Before continuing, you should note that it’s best that State be immutable. I prefer to do this with a struct that only has let properties that are also immutable. Having immutable data makes it impossible to mutate the data in an unsafe way.

An agent effectively has two operations: get and set. Let’s start with getting data.

Fetching the data does the following:

Synchronously run a closure on the dispatch queue.
Call the given closure with the current state.
The closure returns the subset of data it wants.
Return the result to the caller.

And here is the code.

public func fetch<Result>(closure: ((State) -> Result)) -> Result {
    var result: Result!
    queue.sync {
        result = closure(self.state)
    }
    return result
}

Note that an implicitly unwrapped optional must be used here because the Swift compiler is not yet smart enough to know that result is always written to before it is read.

Now for updating the state. It works similarly to the fetch function.

Asynchronously run a closure on the dispatch queue.
Call the given closure with the current state.
The closure returns the new data to store.
Update the internal state.

And here is the code.

public func update(closure: @escaping (State) -> State) {
    queue.async {
        self.state = closure(self.state)
    }
}

The code could just as easily use queue.sync. There’s no need to wait around for the update to complete, so queue.async is typically the desired behavior.

There is one more operation we need. There are times we want to both get and update the data. It is not safe for the caller to fetch the data, change it, then set it. That can lead to race conditions. So, let’s build an operation that does both at the same time.

public func fetchAndUpdate<Result>(closure: (State) -> (Result, State)) -> Result {
    var result: Result!
    queue.sync {
        let (returnValue, newState) = closure(self.state)
        self.state = newState
        result = returnValue
    }
    return result
}

That’s it. In total, SimpleAgent is 36 lines of code, including blank lines. Any Swift developer should be able to look at this code and understand it within a few minutes. Plus you now have a powerful building block for building bigger building blocks such as actors, state machines, and futures. Or it can be used as is.

Building Blocks: Pure State Machine

2018-08-31T04:12:00+00:00

Previously I wrote about my most common building block: Agent. Today I’m going to use Agent to make a bigger building block, namely a pure state machine. It’s implementation is inspired by Elm and Andy Matuschak.

Before continuing, note that “pure” means the state machine is mathematically pure. Or in other words given the same outputs it will always produce the same outputs. This makes testing the state machine trivial.

Let’s start with the basic type definition and constructor.

import Foundation

public final class SimplePureStateMachine<State, Action, Command> {
public typealias ActionHandler = (State, Action) -> (State, Command)

private let state: SimpleAgent<State>
private let handler: ActionHandler

public init(initialState: State, handler: @escaping ActionHandler) {
    self.state = SimpleAgent(state: initialState)
    self.handler = handler
}
}

The state is stored in the agent created previously. This ensures updates are thread safe.

The most notable part of the type definition is ActionHandler. It’s simply a function. As input, it receives the current state and an action (sometimes called an event or message). The action represents an operation to be performed on the state. I typically implement actions as a Swift enum. Here’s an example:

public enum BluetoothAction {
case bluetoothPoweredOn
case bluetoothPoweredOff
case startScan
case stopScan
case scanTimedOut
}

As output, the ActionHandler returns new state and a command (sometimes called an effect). The command represents any side effects the state machine would like performed on its behalf. Since the state machine is pure, it can’t do things like performing network requests or access a database. Some external entity will receive the commands, perform them, and report back to the state machine with an action.

For those interested, this type of state machine is known as a Mealy machine.

Now that you are thoroughly lost in the theory, let’s actually implement the rest of the state machine. It turns out there is only one function left to implement: handleAction.

public func handleAction(_ action: Action) -> Command {
return state.fetchAndUpdate {
    let (newState, command) = self.handler($0, action)
    return (command, newState)
}
}

That’s it. All the real work is done by SimpleAgent and the ActionHandler. This leaves SimplePureStateMachine weighing in at a whopping 24 lines, including blank lines.

Before I conclude, I’ll demonstrate SimplePureStateMachine. That will help clear up the mystery behind ActionHandler. For this example, I will make a simple coin-operated turnstile.

enum TurnstileState {
case locked
case unlocked
}

enum TurnstileAction {
case insertToken
case admitPerson
}

enum TurnstileCommand {
case lock
case unlock
case ejectToken
case notifySecurity
}

let turnstile = SimplePureStateMachine<TurnstileState, TurnstileAction, TurnstileCommand>(initialState: .locked) { state, action in
switch (state, action) {
case (.locked, .insertToken):
    return (.unlocked, .unlock)

case (.locked, .admitPerson):
    return (.locked, .notifySecurity)

case (.unlocked, .admitPerson):
    return (.locked, .lock)

case (.unlocked, .insertToken):
    return (.unlocked, .ejectToken)
}
}

turnstile.handleAction(.insertToken)   // Command: unlock
turnstile.handleAction(.admitPerson)   // Command: lock
turnstile.handleAction(.admitPerson)   // Command: notifySecurity
turnstile.handleAction(.insertToken)   // Command: unlock
turnstile.handleAction(.insertToken)   // Command: ejectToken

Again, the great win with a pure state machine is the logic can be tested without any side effects such as inadvertedly alerting security. Also, the state machine doesn’t care how the side effects are implemented. This leaves us free to change that detail however and whenever we want without chaning the state machine. Now that’s modularity.

TIL: Sorting by Multiple Keys in Elixir

2018-01-05T03:30:00+00:00

While working on Advent of Code 2017 I inadvertedly discovered how to sort collections by multiple keys. In the past, I’ve always written elaborate functions like this:

contacts
|> Enum.sort(fn x, y ->
  if x.last_name == y.last_name do
    x.first_name < y.first_name
  else
    x.last_name < y.last_name
  end
end)

Now I’ve found a simpler solution.

In the example above we have a list of contacts to sort by last name then first name. We can do so like this:

contacts
|> Enum.sort_by(&{&1.last_name, &1.first_name})

That’s it. Just return a tuple with the list of values to sort by. (Note, this example uses sort_by instead of sort.) If two contacts have the same last name, then the first names will be compared. This can be done for any number of values.

This works with min and max too.

The down side of this approach is that it assumes that you want an ascending or descending sort for all the listed values. In general, you must use an elaborate function to handle mixed sort orders.

There is a special case for numbers though. Let’s say you have a list of games and you want the game with the highest score. However, if two or more games have the same highest score, you want the first game to achieve that score. You can do so like this:

games
|> Stream.with_index
|> Enum.max_by(fn {x, n} -> {x.score, -n} end)
|> elem(0)

Basically, the index is multiplied by -1 to get the minimum.

Sorting is a common operation and it doesn’t need to be complicated.