Magic: The Gathering has been called “the best game ever created” by players and commentators across three decades of competitive play. Whether or not one agrees with that assessment, the commercial success of Magic is difficult to dispute. Richard Garfield’s 1993 creation launched the collectible card game industry, and Magic remains commercially viable more than thirty years later. Over 200 sets have been released. Tens of thousands of unique cards have been printed. The game has more players today than at any previous point in its history.
What makes Magic interesting as a subject of analysis is not just the game itself but the physical artifact at its center: the card. A Magic card is an extraordinarily dense physical data structure. It encodes identity, cost, type, rules, metadata, and collectibility information on a single piece of printed cardstock. This density makes Magic cards a useful model for understanding virtual goods, digital items that share many of the same structural properties but exist without the physical substrate.
This article examines the anatomy of a Magic card, explains why the card structure maps cleanly to the economics of virtual goods, and explores what that mapping reveals about the production, distribution, and valuation of digital items. A companion article, Metagaming as a Framework for Real-Life Strategy, covers the strategic dynamics of Magic including chase cards, bulk cards, and meta-defining game tokens.
# Date (UTC)
$ date -u "+%Y-%m-%d %H:%M:%S +0000"
2026-02-13 07:51:26 +0000
# OS and Version
$ uname -vm
Darwin Kernel Version 23.6.0: Mon Jul 29 21:14:30 PDT 2024; root:xnu-10063.141.2~1/RELEASE_ARM64_T6000 arm64
$ sw_vers
ProductName: macOS
ProductVersion: 14.6.1
BuildVersion: 23G93
# Hardware Information
$ system_profiler SPHardwareDataType | sed -n '8,10p'
Chip: Apple M1 Max
Total Number of Cores: 10 (8 performance and 2 efficiency)
Memory: 32 GB
# Shell and Version
$ echo "${SHELL}"
/bin/bash
$ "${SHELL}" --version | head -n 1
GNU bash, version 3.2.57(1)-release (arm64-apple-darwin23)
# Claude Code Installation Versions
$ claude --version
2.1.37 (Claude Code)
A Magic card is a standardized 63mm by 88mm piece of printed cardstock. Every card in the game shares the same physical dimensions and the same card back, a design choice that ensures face-down cards are nominally indistinguishable from one another. This uniformity is structurally important. It means that a player’s hand of cards and the top card of their deck carry no visible information to the opponent, enabling hidden information as a core game mechanic.
The face of a Magic card is divided into several distinct information regions. Each region serves a specific function in the game’s rules engine. The following breakdown uses the standard card frame introduced in the 2003 revision and refined in subsequent updates.
The card name appears at the top left of the card face. It is the primary identifier for the card. Game rules, deck construction constraints, and card interactions all reference cards by name. A standard deck may contain at most four copies of any card with a given name, with the exception of basic land cards.
The mana cost appears at the top right of the card face. It specifies the resources required to play the card. Mana costs use a symbolic notation that encodes both the total amount of mana required and the specific colors of mana that must be included. For example, a cost of 2R means two mana of any color plus one red mana. The five colors of mana in Magic are white (W), blue (U), black (B), red (R), and green (G). Colorless mana and hybrid mana costs extend this system further.
The mana cost is a critical game design lever. It determines when a card can be played and what strategic trade-offs a player must make to include it in a deck. Powerful effects with low mana costs tend to become chase cards because they offer disproportionate value.
The illustration occupies the largest single region of the card face. Magic has commissioned original artwork for every card from thousands of artists over the game’s history. The art serves no mechanical function but contributes significantly to the card’s identity, collectibility, and market value. Cards with art by sought-after artists or with particularly striking compositions can command premiums independent of gameplay value.
The type line appears below the card art. It specifies the card’s type, and optionally, its subtypes and supertypes.
The major card types include Creature, Instant, Sorcery, Enchantment, Artifact, Planeswalker, and Land. Each type has distinct rules for how and when the card can be played and how it behaves on the battlefield. Subtypes provide further classification. A creature might be a “Human Wizard” or a “Goblin Warrior.” An instant might be a “Lesson.” Supertypes like “Legendary” or “Basic” add additional rules constraints.
The type line functions as a classification system analogous to a type hierarchy in a programming language. Cards interact with each other based on type. A spell that says “destroy target creature” operates on the Creature type. A spell that says “search your library for a Goblin” operates on the Goblin subtype. This system enables combinatorial interactions without requiring each interaction to be individually specified.
The set symbol appears on the right side of the type line. It identifies which set the card was printed in and indicates the card’s rarity through color.
The four standard rarity levels are common (black or white symbol), uncommon (silver), rare (gold), and mythic rare (red-orange). Rarity determines how frequently a card appears in randomized booster packs. A mythic rare appears roughly once in every eight packs, while commons fill the majority of each pack.
Rarity is the primary supply-side mechanism that creates scarcity and drives secondary market prices. A powerful mythic rare is scarce by design, while a powerful common is abundant.
The rules text box occupies the center-lower portion of the card. It contains the card’s mechanical instructions.
Magic’s rules system operates on a principle that Richard Garfield has described as making the game “bigger than the box.” A base set of comprehensive rules governs the game, but individual cards can create exceptions to those rules. A card might say “this creature cannot be blocked,” overriding the default blocking rules. Another might say “you may play an additional land this turn,” overriding the one-land-per-turn rule.
This exception-based design is what gives Magic its combinatorial depth. The base rules are learnable. The card-specific exceptions are printed on the cards themselves. New cards can introduce entirely new mechanics without requiring changes to the core rules engine. In software engineering terms, the cards are plugins to a stable runtime.
Creature cards display two numbers in the bottom right corner of the card, separated by a slash. The first number is the creature’s power, which determines how much damage it deals in combat. The second is its toughness, which determines how much damage it can sustain before being destroyed.
A 2/3 creature deals 2 damage and survives 3 damage. These values interact with the mana cost to define the creature’s efficiency. A 2/3 creature for two mana is more efficient than a 2/3 creature for five mana. This efficiency calculation is central to competitive deck construction.
The bottom edge of the card contains a line of collector information that serves no gameplay function but encodes metadata about the card’s production.
A modern collector information line contains the collector number (the card’s position within the set, such as “123/250”), the set code (a three-letter identifier like “MKM” for Murders at Karlov Manor), the rarity indicator (C, U, R, or M), the card’s language code, and the artist credit. Below this line, a copyright notice identifies the card as a product of Wizards of the Coast and Hasbro.
Since 2014, rare and mythic rare cards also carry a holographic security stamp at the bottom center of the card. This stamp serves as an anti-counterfeiting measure, reflecting the fact that some individual cards have secondary market values exceeding hundreds of dollars.
When space permits, the rules text box may include flavor text printed in italics below the mechanical rules. Flavor text has no game function. It provides narrative context, world-building details, or character quotes that connect the card to Magic’s fictional multiverse.
The structural analysis above reveals why Magic cards are a useful physical model for understanding virtual goods. The key insight is that a Magic card is essentially a physical data structure with a near-zero marginal cost of production.
The cost of printing a single Magic card is trivially small when amortized across a production run. The cardstock, ink, and packaging cost fractions of a cent per card. A chase mythic rare that sells for fifty dollars on the secondary market costs the same to print as a bulk common that sells for a fraction of a cent. If premium treatments like foil stamping and alternate art variants are set aside, the marginal cost of producing any individual card is effectively identical regardless of its gameplay value or secondary market price.
This is the defining characteristic of virtual goods as well. A digital item in a video game, whether it is a cosmetic skin, a weapon, or a currency unit, has a near-zero marginal cost of distribution. Once the asset has been created, delivering one additional copy to one additional user costs effectively nothing. The physical card and the virtual item share the same economic structure: high fixed costs of creation, near-zero marginal costs of distribution.
The non-trivial costs in Magic card production are research and development costs. Designing a Magic set requires game designers, developers, playtesters, artists, editors, and production staff working over a multi-year development cycle. Each set must be balanced internally, balanced against the existing card pool, and tested across multiple competitive formats. This R&D effort is expensive, but it is a fixed cost that is amortized across millions of printed cards.
Virtual goods share this cost structure precisely. The development cost of a new character class in an online game, a new weapon skin, or a new expansion pack is real and often substantial. The distribution cost per unit is negligible. The economic challenge in both cases is identical: recover fixed R&D costs through volume distribution of a product whose marginal cost approaches zero.
Magic uses rarity to create artificial scarcity. A mythic rare is not more expensive to print than a common. It is scarce because the production process distributes mythic rares at a lower frequency than commons in randomized booster packs. This designed scarcity drives secondary market prices.
Virtual goods replicate this pattern explicitly. Drop rates in video games function identically to rarity slots in booster packs. A legendary weapon that drops once per thousand encounters is not more expensive to generate than a common weapon. It is scarce because the game’s random number generator distributes it infrequently. The scarcity is artificial, intentional, and economically productive.
The secondary market for Magic cards produces a stark value distribution. A small number of cards become chase cards, sought after by competitive players and commanding prices of tens or hundreds of dollars. The vast majority of cards, including most rares, become bulk junk with negligible secondary market value.
As discussed in Metagaming as a Framework for Real-Life Strategy, card value is driven by the competitive meta. Cards that enable dominant strategies become expensive. Cards that the meta does not favor become bulk regardless of their design creativity or mechanical interest. The Screaming Nemesis example from that article illustrates how a single card can rise to chase status through meta dominance and crash to near-bulk prices after a ban.
This distribution is not unique to Magic. Virtual goods in online games exhibit the same pattern. A small number of items, those that confer competitive advantage or social status, command high prices on secondary markets. The remainder has negligible value. The production cost is the same for both categories.
Magic cards have well-established secondary market prices despite Wizards of the Coast’s official position that booster packs are sold as sealed products at a uniform retail price. The secondary market exists because players assign subjective value to individual cards based on competitive utility, collectibility, and aesthetics.
Virtual goods demonstrate this same phenomenon. Despite End User License Agreements (EULAs) that typically prohibit Real Money Trading (RMT), secondary markets for virtual items are widespread and economically significant. Players assign real monetary value to digital items based on the same factors that drive Magic card prices: competitive utility, rarity, and social signaling.
The economic lesson is that prohibiting secondary markets through legal agreements does not eliminate the underlying demand. When items have subjective value, whether physical or virtual, markets emerge to facilitate exchange. Magic’s established and sanctioned secondary market is simply the transparent version of what virtual goods economies produce through unauthorized channels.
Several observations flow from this comparison.
Cards as physical APIs. A Magic card is a self-documenting interface to the game’s rules engine. The card name is the identifier. The mana cost is the calling convention. The type line is the type signature. The rules text is the implementation. The power and toughness are the return values. This is not a metaphor. The Comprehensive Rules document that governs Magic is a formal specification, and each card is a concrete implementation of an interface defined by that specification. Virtual goods in well-designed games follow the same pattern: each item is an instance of a type defined by the game’s rules engine.
The printing press as a distribution platform. Magic’s printing infrastructure is functionally equivalent to a digital distribution platform. Both take a designed artifact, replicate it at near-zero marginal cost, and distribute it through a supply chain that introduces artificial scarcity to support tiered pricing. The booster pack is the loot box. The card shop is the marketplace. The difference is substrate, not structure.
Rarity as a game design tool and an economic tool simultaneously. Rarity in Magic serves two purposes that are often conflated. As a game design tool, rarity controls the complexity of the draft environment by limiting how often players encounter mechanically complex cards. As an economic tool, rarity creates scarcity that drives revenue. Virtual goods designers face the same tension. Drop rates affect both gameplay balance and monetization. Optimizing for one objective can undermine the other.
The bulk junk problem reveals value asymmetry. Most Magic cards have negligible monetary value despite representing genuine R&D investment. A bulk common may feature innovative mechanics, beautiful artwork, and careful flavor text. Its low value reflects not a failure of design but a structural consequence of meta dynamics and supply abundance. Virtual goods face the same problem. Most items in a game’s catalog have negligible player interest. The R&D cost is real. The perceived value is not. This asymmetry is inherent to any system that produces many items but concentrates demand on a few.
Physical cards prove that scarcity alone does not create value. Many rare Magic cards are worth less than a dollar. Rarity is necessary but not sufficient for high market value. The card must also be competitively relevant, aesthetically desirable, or culturally significant. Virtual goods designers who assume that low drop rates automatically create valuable items are making the same mistake as a Magic set designer who assumes every mythic rare will be a chase card. The meta, not the rarity, determines value.
Magic cards are physical data structures with near-zero marginal production costs, designed scarcity, and subjective value driven by competitive utility and collectibility. Virtual goods share every one of these properties. The only structural difference is the substrate: cardstock versus software.
This is not a coincidence. Magic: The Gathering was designed in 1993, before the modern virtual goods economy existed. Richard Garfield solved many of the same design problems that virtual goods designers would encounter a decade later: how to distribute items at scale, how to create and maintain scarcity, how to balance gameplay value against economic value, and how to sustain a market where most individual items have negligible worth but the system as a whole generates substantial revenue.
The lesson for virtual goods designers is that physical card games have thirty years of empirical evidence about what works and what fails. Rarity without competitive relevance does not create value. Artificial scarcity without balanced gameplay drives player frustration. Secondary markets emerge whether sanctioned or not. And the meta, the emergent strategic equilibrium among the player population, is the ultimate arbiter of which items matter and which become bulk junk.
What Magic: The Gathering Can Teach Us by Raph Koster on Game Developer, examining how Magic’s design principles apply to broader game design challenges.
Metagaming as a Framework for Real-Life Strategy, the companion article covering competitive dynamics, chase cards, bulk cards, and how the meta determines value.
Scryfall, a comprehensive Magic card database and search engine with free API access to card data, images, and pricing information.
The Zero Marginal Cost Society by Jeremy Rifkin, examining how near-zero marginal costs are reshaping economic structures across industries.
Virtual Economies: Design and Analysis by Vili Lehdonvirta and Edward Castronova, a scholarly treatment of virtual goods economics, including RMT, artificial scarcity, and platform design.
The phases of chess are broadly applicable to many, if not most, games. Massively multiplayer online games (MMOs) are a little different because they are designed to be played forever. Therefore, it may seem odd to analyze them with a model that ends with checkmating for a win. The only way to “beat” an MMO is to quit playing, and this has profound implications for the MMO operation.
A game of chess moves through the following phases.
There are also a few alternate end states.
Users of an MMO progress through phases that parallel those of a chess game.
There are also alternate end states.
During the opening phase, a player jumps through all the hoops required to start the game. This includes things like the following.
People write articles and make videos about the “best” way to start popular games, and many prospective players use them to make an educated start. If anything goes wrong during onboarding, players are likely to walk away forever. Instant checkmate.
Three main things happen during the board development phase. The player character fills out core gear and learns the fundamental abilities that will carry it through the rest of the game. The player learns how to play the game, and the character or faction they decided to start as. The player becomes habituated to having an alter ego in the MMO’s particular fantasy world. Players are still sensitive to bad experiences when they are warming up to a new MMO.
At this point, the player knows the basics of the game and what they decided to play. They have also consistently made time in their life to commit to the MMO. Active midgame players are the most likely to put up with problems because they are invested in the game and there are still things they want to do. Starting a new MMO is work and they are already set up here. The MMO operator’s goal is to keep players paying for the privilege to happily play midgame content for as long as possible, ideally forever.
A check is any situation that causes a player to consider quitting the game. Most players stick through most checks, but these are the situations where players are most likely to quit. Checks are unavoidable, but paying attention to them is important for user retention. Checks include things like the following.
Like a check in chess, these kinds of situations require immediate reaction to retain users.
All players eventually quit the game for one reason or another. As an extreme example, nobody is immortal. When a player dies, that is an instant checkmate. Especially toxic community interaction? Checkmate. Change in life circumstances? Checkmate. Bored and want to do something else? Checkmate.
The chess phases are a simple model for reasoning about MMO user progression- opening, board development, midgame, check, and checkmate. Therefore, it can be used to easily reason about user and mental energy can be expended on hard problems and complex solutions.
No singles phase is more important than another. Players need to be onboarded. They need to learn the game and become habituated to playing it. They need to have content to play to remain invested and engaged in the experience. Situations will occur that make players unhappy and cause them to consider quitting. Finally, players will leave despite the developer’s best efforts to keep them engaged.
]]>Go and chess are two classic strategy games with simple rules that are hard to master. Go arguably has simpler rules than chess, but the game is arguably the harder of the two to master. Go is essentially what you get if a strategy is reduced to the minimum number of possible components. Go gets a lot of things right. This post will discuss the scope of Go’s rules, and discuss why it is an important study for modern game design.
This section will cover the scope of Go without going into details. Readers are expected to know the rules, or know how to find them. A typical go set includes the following.
Different sized Go boards are played on, and a non-standard board is typically going to be square with the length of the sides being an odd number. Note that 19x19 is 361. This implies that a set has enough stones to fill the whole board, with black getting the extra odd stone because it moves first. The following board sizes are also used.
Note that Go only has one kind of game token- stones. Black and white stones are mechanically identical and differ only in who controls them. Go is a battle for territorial control, and stones could abstractly be considered soldiers on a battlefield.
Players take turns placing stones, starting with black. If black receives a handicap, the handicap stones are placed and then white moves (black is the weaker player). Groups of stones that are completely surrounded are removed from the board. Passing is legal, but it is only beneficial at the end of the game.
The basic concepts of Go include the following.
Go has a few additional rules.
All else being equal, Go is a game where a player who understands the game better will consistently beat weaker opponents. Go has a handicap system where the game starts off unequally, and this allows players of different skill levels to enjoy playing against one another. The difference in player grade levels indicates the number of hanicap stones, and the weaker player starts with anywhere from two to nine extra stones.
Black has an advantage because it moves first. If players are of equal skill, white starts with bonus points called komi. Over millennia of play, people have determined that playing first is worth about sevent points. Tournaments typically give white seven and a half points to eliminate the possibility of a draw.
The complete game state for a game of Go can be represented in under one hundred bytes if it is optimized for size.
46 bytes contains 368 bits. 92 bytes for all stone locations works out to 14 unused bits. Four of these can be used for game state flags. Captured stones can then be stored in one byte and any remaining bits. Add four more bytes to store information for determining ko, and the total state is 98 bytes.
Alternatively, one byte can be used for each board location and flag, four bytes can be used for each player’s score for a total of 373 bytes. Add another 16 bytes for ko and the grand total is 389 bytes, or about 400.
The complexity of Go is not in the static game state, but in the possible number of game states. Each board location can have a black stone, a white stone, or it can be empty. This works out to 3 to the power of 361 possible board states, or a number so large it is a one followed by 172 zeros. Despite many of those states being illegal, the magnitude of possibilities is way over one googol. This is far too many for static analysis without accounting for captured stones, passing, or ko.
For comparison, a chess board has 64 squares and each square has 13 possible states- empty, six white pieces, and six black pieces. This works out to a one followed by only 71 zeroes, and the majority of the states are impossible in practice. Go has a magnitude of a googol more possible game states than chess.
In a previous post, I wrote about using chess as a model for other games. Go has less clearly defined phases, but the same analysis can be used.
Standard openings typically involve claiming corners or contesting a handicap. The board is arguably developed when rudimentary battle lines are established at all corners and the sides of the board- essentially all handicap locations. The midgame begins after all major board zones have been claimed or contested. Therefore, a nine-stone handicap is strong because the weaker player literally starts with a board presence everywhere.
A check could be threatening a major stone group or securing a zone of the board. A checkmate is a situation where the game is hopeless for the other player. Unlike many other games, Go often ends when all locations on the board have been played to their tactical conclusion. The two patterns are playing to the bitter end, or playing until one player simply concedes.
Go is brilliant because deep gameplay emerges from only a single type of game token and a board to place the tokens on. This makes it the ultimate reduction in unnecessary complexity. Every single rules has a very good reason for existing.
Many games fail to solve the above problems.
In conclusion, Go’s level of minimal design is likely inappropriate for modern products, but its solutions to fundamental game design problems are absolutely worth being aware of.
]]>Models are useful to help reason about complex problems. This post will describe how chess can be used as a model to reason about more complex games. Chess will specifically be compared to Civilization 5, Magic the Gathering, and Final Fantasy 1.
This session is going to cover the scope of the game of chess, without actually going into detail on any of the rules. Readers are expected to know the rules or know how to find them.
A chess set includes one board and 32 pieces- 16 black and 16 white. The board is an eight by eight grid. Squares have a rank and file.
Each player gets the following six kinds of pieces. Point values have no mechanical role, but they help players reason about the game.
The rules for moving and capturing pieces are fairly simple. In addition to learning how the different kinds of pieces move, chess has a few special rules.
There are also rules that relate to ending the game.
Every game starts with all pieces in predefined locations, and white moves first. Finally, note that chess has sufficiently few components that people have been known to draw paper chess sets for lack of dedicated pieces.
If a game of chess is played from start to finish, it moves through the following phases.
On the very first move, each of the eight pawns can be moved one or two spaces, and each of the two knights can also be moved into one of two locations. Therefore, white can make one of twenty first moves, and black can make one of twenty first responses. The first move is the most important because it opens up options for the second and subsequent moves. Some of the first moves make more sense than others.
The opening is a set of predefined moves to start the game. Openings can be memorized, and some are stronger than others. Different openings lend themselves to different styles of play and set the start of the game. An extreme example is the two move checkmate, where white opens F and G files and black responds with the queen for a checkmate.
Next, players focus on developing the board. A piece is developed once it has been moved from its starting position. The board development phase generally involves castling, developing backrow pieces, and getting all the non-castle side pawns into a useful formation. Where board development starts and ends can be fuzzy, but the goal is to get the pieces somewhere useful. Many of the board development phase moves and responses can be memorized.
Once the board has been developed, the midgame begins. At this point, the board is set and players can no longer rely on having memorized exact board states and positions. They need to use strategy and tactics to play chess. The better player will do more damage and wind up in a more favorable position.
A check occurs when one player threatens the other player’s king. The rules of chess dictate that a player must get their king out of check if it is threatened. When in check, a player’s options are limited. Sometimes this is not a problem, other times it can be used to set up situations where the player in check loses material because they need to focus on the king.
Simply playing better in midgame and putting the opponent’s king in check is not enough to win a game of chess. The opponent’s king must be put in a checkmate to win. Checkmate occurs when it is impossible for the opponent to get their king to safety. Learning endgame checkmates is a skill that can be developed. Depending on the circumstances, this knowledge can be used to win, recover from a losing position, or play for a draw.
Although the details depend on the title, many games move through the same phases as chess.
Openings are a set of predefined moves that propel the game in one of many directions. They can be memorized, and people often put a lot of thought into the analysis of openings.
The board development phase consists of collecting and deploying a complete set of game tokens usefully. Campaign-based games may have per-stage board development and campaign level board development. Note that board development often needs to occur while being actively resisted.
The timing can be fuzzy, but at some point the board is developed, and the player just needs to play the game. This is the midgame. Some games have an extremely long midgame.
A check occurs when a player threatens a victory, or signals progress towards a victory. Unlike chess, it may not require an immediate response. Sometimes, however, a check does indicate a situation where one or more players need to intervene so as not to lose the game.
A checkmate occurs when a player meets all the criteria for a win condition. Like chess, a checkmate often requires knowing the criteria to secure a victory. Midgame tactics and endgame criteria are often different, but not unrelated.
In Civilization 5, the opening is the initial build queue. Many beginners tend to first build a monument. An example of a more complex opening is scout, scout, shrine, granary, monument, settler. Openings can be memorized and analyzed. Tactically, deviating from an opening rarely makes sense.
Civ 5 is far more complex than chess, but the board development phase likely concludes around the time all early game cities have been founded and luxury resources have been improved. Hypothetically, cities can be founded or conquered at any time, and tile improvements are optional, but there does tend to be a point when cities are settled and focus shifts to playing with what is on the board. Note that city expansions need to be planted despite barbarians, hostile players, and competing priorities.
The midgame consists of development and conquest that happens after the core cities are in place. This is the bulk of the game. A bad initial board state can lose games, but running with a developed board is required to win games.
Civ 5 has multiple victory conditions- score, domination, diplomacy, science, and culture. Score is the default win condition if the game goes on for too long without another more specific victory condition having been met. The other victory types have conditions that could be considered a check.
Likewise, a checkmate occurs when all the conditions for a specific victory type have been met.
Midgame development and warfare are not enough to win the game. Especially poor play will result in a loss, but a checkmate requires very specific actions.
Note that telegraphing a check may elicit a response from one or more other players. War may be declared, or an opponent may double down on their victory push.
Magic the Gathering (MTG) is a game where players build decks with collectable cards. Unlike other games, different players can show up with completely different decks of game tokens, but the game can still be modeled using the same chess phases.
Players draw 7 random cards at the beginning of the game, so openings are not as reliable as chess. Some hands are just bad. Building a reliable deck is a skill, and certain cards will likely be available in the first few turns if included in sufficient quantity. Therefore, the opening consists of cards that are likely available and playable during the first few turns of the game.
Board development largely consists of summoning creatures, but enchantments and artifacts can also be played. During the first few turns in a game, players will typically develop a board to face down their opponent.
A check is any problem that threatens to kill the opponent if left unanswered. Even a weak 1/1 creature can be a check if the opponent has no board state. A checkmate occurs when one player is reduced to zero life points, or an alternate win condition is met.
The phases of chess can also be used as an analogy for collecting cards and building decks. Most people open with some sort of starter deck, but there are different ways to start playing a collectible trading card game. Board development consists of getting enough cards together to build a competitive deck. Check is a player’s first meta deck, and checkmate is the point where the player has the knowledge and tools to play against all the common meta decks.
An RPG is a campaign-based game. Each dungeon can be modelled with the chess phases, as can the party in the context of the greater adventure.
At the campaign level, the opening is simply the player’s initial party of four heroes. Board development consists of equipping the party, learning useful early game spells, and maybe gaining a few levels. The midgame consists of playing through the game after the party has a full set of equipment.
Defeating each of the four fiends is arguably a check, and defeating the last boss is a checkmate. The endgame content is largely the same as the midgame content.
At the dungeon level, the opening consists of picking a direction. Strategically approaching dungeons is possible for people who are familiar with the game.
Board development consists of collecting key pieces of treasure. The party keeps the gear even if a tactical retreat is necessary. A check is any milestone that threatens to make the dungeon easy to beat, and a checkmate is actually beating the dungeon. Conversely, anything that threatens a party wipe could be considered a check.
Compared to modern commercial games, chess is simple and easy to reason about. It only has 32 pieces that are placed on a 64-square grid. More complex games can often be broken into phases that parallel the progression of a chess match.
Fortran is used for heavy number crunching in mathematical and scientific computing. This post will start by covering calling Fortran from C. It will then discuss using Fortran on the Panic Playdate, both the simulator and hardware.
$ date -u "+%Y-%m-%d %H:%M:%S +0000"
2022-10-10 21:55:03 +0000
$ uname -vm
Darwin Kernel Version 21.6.0: Mon Aug 22 20:19:52 PDT 2022; root:xnu-8020.140.49~2/RELEASE_ARM64_T6000 arm64
$ ex -s +'%s/<[^>].\{-}>//ge' +'%s/\s\+//e' +'%norm J' +'g/^$/d' +%p +q! /System/Library/CoreServices/SystemVersion.plist | grep -E 'ProductName|ProductVersion' | sed 's/^[^ ]* //g' | sed 'N; s/\n/ /g'
macOS 12.6
$ echo "${SHELL}"
/bin/bash
$ "${SHELL}" --version | head -n 1
GNU bash, version 3.2.57(1)-release (arm64-apple-darwin21)
$ cat "${HOME}/Developer/PlaydateSDK/VERSION.txt"
1.12.3
$ gfortran -v 2> >(tail -1)
gcc version 12.2.0 (MacPorts gcc12 12.2.0_0+stdlib_flag)
$ arm-none-eabi-gfortran -v 2> >(tail -1)
gcc version 11.3.1 20220712 (Arm GNU Toolchain 11.3.Rel1)This section assumes that gcc and gfortran are installed. First, create a new project.
PROJECT="c_fortran_interop_example"
mkdir "${PROJECT}"
cd "${PROJECT}"Add main.c.
main.c
#include <stdio.h>
#include <stdlib.h>
#include "fast_sqrt.h"
int main(int argc, char **argv) {
for (int i=1; i<argc; i++) {
double input = atof(argv[i]);
double output = fast_sqrt(input);
printf("The square root of %.3f is %.3f.\n", input, output);
}
return 0;
}Add fast_sqrt.h for interoperation with C.
fast_sqrt.h
#ifndef FAST_SQRT_H
#define FAST_SQRT_H
extern double fast_sqrt(double);
#endif // FAST_SQRT_HAdd the Fortran implementation of fast_sqrt().
fast_sqrt.f90
function fast_sqrt( x ) result( y ) bind( C, name="fast_sqrt" )
use iso_c_binding, only: c_double
implicit none
real(c_double), VALUE :: x
real(c_double) :: y
y = sqrt(x)
end functionCreate a Makefile to capture simple logic for building and testing the program. The C and Fortran files are compiled into object files to combine into a binary. The testing code calls the program with the numbers from zero to ten as test parameters.
Makefile
.PHONEY: all clean force run test
CFLAGS=-Wall
FC=gfortran
FCFLAGS=-Wall
TARGET=fast_sqrt
OBJS=main.o fast_sqrt.o
all: $(TARGET)
force: clean all
$(TARGET): $(OBJS)
$(FC) $(CFLAGS) $^ -o $@
%.o: %.c
$(CC) $(CFLAGS) -c $< -o $@
%.o: %.f90
$(FC) $(FCFLAGS) -c $< -o $@
test: $(TARGET) run
run:
for i in {0..10}; do ./$(TARGET) $$i; done
clean:
rm -rf *.o $(TARGET)Build and test the program.
$ make test
cc -Wall -c main.c -o main.o
The square root of 0.000 is 0.000.
The square root of 1.000 is 1.000.
The square root of 2.000 is 1.414.
The square root of 3.000 is 1.732.
The square root of 4.000 is 2.000.
The square root of 5.000 is 2.236.
The square root of 6.000 is 2.449.
The square root of 7.000 is 2.646.
The square root of 8.000 is 2.828.
The square root of 9.000 is 3.000.
The square root of 10.000 is 3.162.Calling Fortran from C on the Playdate simulator is much the same as in the previous section. The Playdate simulator runs on the development machine and uses the host architecture. Therefore, cross-compilation is not necessary. The Hello World C API example is a reasonable project template, so make a copy.
PROJECT="fortran_test"
PROJECT_PATH="my_playdate_projects"
cd "${PROJECT_PATH}"
cp -r "${PLAYDATE_SDK_PATH}/C_API/Examples/Hello World/" "${PROJECT}"
cd "${PROJECT}"Next, update pdxinfo.
Source/pdxinfo
name=FortranTest
author=Brendan Sechter
description=Fortran on Playdate proof of concept.
bundleID=com.sennue.poc_fortrantest
imagePath=The main.c and main.h files from an earlier post, ASM Playdate Development, can be used for this project. Modify main.c.
src/main.c
#include "fast_sqrt.h"
#include "main.h"
#include "pd_api.h"
const char* fontpath = "/System/Fonts/Asheville-Sans-14-Bold.pft";
const LCDPattern gray50 = {
// Bitmap
0b10101010,
0b01010101,
0b10101010,
0b01010101,
0b10101010,
0b01010101,
0b10101010,
0b01010101,
// Mask
0b11111111,
0b11111111,
0b11111111,
0b11111111,
0b11111111,
0b11111111,
0b11111111,
0b11111111,
};
void initProgramState(struct ProgramState *ps, PlaydateAPI *pd)
{
const char *errorMessage;
ps->pd = pd;
ps->font = NULL;
ps->font = pd->graphics->loadFont(fontpath, &errorMessage);
if (NULL == ps->font) {
pd->system->error("%s:%i Couldn't load font %s: %s",
__FILE__, __LINE__, fontpath, errorMessage
);
}
ps->previousInput = 0;
ps->strokeWidth = 2;
ps->x = (LCD_COLUMNS - TEXT_WIDTH) / 2;
ps->y = (LCD_ROWS - TEXT_HEIGHT) / 2;
ps->dx = 1;
ps->dy = 1;
}
#ifdef _WINDLL
__declspec(dllexport)
#endif
int eventHandler(PlaydateAPI* pd, PDSystemEvent event, uint32_t arg)
{
(void)arg; // only used for kEventKeyPressed == event
static struct ProgramState *ps = NULL;
switch (event) {
case kEventInit:
ps = pd->system->realloc(ps, sizeof(struct ProgramState));
initProgramState(ps, pd);
pd->system->setUpdateCallback(update, (void *)ps);
break;
case kEventTerminate:
pd->system->realloc(ps, 0);
ps = NULL;
break;
default:
// do nothing
break;
};
return 0;
}
static int update(void* userdata)
{
struct ProgramState *ps = (struct ProgramState *)userdata;
handleInput(ps);
draw(ps);
return 1;
}
void handleInput(struct ProgramState *ps) {
PlaydateAPI* pd = ps->pd;
int x_direction = 0;
int y_direction = 0;
// dpad input
PDButtons currentInput;
pd->system->getButtonState(¤tInput, NULL, NULL);
if ( currentInput & kButtonUp ) {
ps->y--;
} else if ( currentInput & kButtonDown ) {
ps->y++;
} else {
y_direction = 1;
}
if ( currentInput & kButtonLeft ) {
ps->x--;
} else if ( currentInput & kButtonRight ) {
ps->x++;
} else {
x_direction = 1;
}
if (( currentInput & kButtonA ) && !( ps->previousInput & kButtonA )) {
ps->dx *= -1;
}
if (( currentInput & kButtonB ) && !( ps->previousInput & kButtonB )) {
ps->dy *= -1;
}
ps->previousInput = currentInput;
int steps;
if (pd->system->isCrankDocked()) {
steps = 1;
} else {
steps = pd->system->getCrankChange();
if (steps < 0) {
steps = -steps;
x_direction = -1;
y_direction = -1;
}
}
for (int i = 0; i < steps; i++) {
ps->x += ps->dx * x_direction;
ps->y += ps->dy * y_direction;
// bounce
if ( ps->x < 0 || LCD_COLUMNS < ps->x ) {
ps->dx *= -1;
}
if ( ps->y < 0 || LCD_ROWS < ps->y ) {
ps->dy *= -1;
}
}
}
int adjustTextPosition(int x, int w, int min, int max) {
if (x < min) {
return min;
} else if (max < x + w) {
return max - w;
} // else
return x;
}
void keepTextOnScreen(int *x_ptr, int *y_ptr, int x, int y) {
*x_ptr = adjustTextPosition(x, TEXT_WIDTH, 0, LCD_COLUMNS);
*y_ptr = adjustTextPosition(y, TEXT_HEIGHT, 0, LCD_ROWS);
}
void drawOutlinedText(
PlaydateAPI* pd,
const char *message,
int x,
int y,
int outlineWidth,
LCDColor textColor,
LCDColor outlineColor
) {
pd->graphics->setDrawMode(outlineColor);
pd->graphics->drawText(
message, strlen(message), kASCIIEncoding, x - outlineWidth, y
);
pd->graphics->drawText(
message, strlen(message), kASCIIEncoding, x + outlineWidth, y
);
pd->graphics->drawText(
message, strlen(message), kASCIIEncoding, x, y - outlineWidth
);
pd->graphics->drawText(
message, strlen(message), kASCIIEncoding, x, y + outlineWidth
);
pd->graphics->setDrawMode(textColor);
pd->graphics->drawText(message, strlen(message), kASCIIEncoding, x, y);
}
void draw(struct ProgramState *ps)
{
PlaydateAPI* pd = ps->pd;
int stroke = ps->strokeWidth;;
int x = ps->x;
int y = ps->y;
char *message = NULL;
int text_x, text_y;
pd->graphics->clear((LCDColor)gray50);
pd->graphics->setFont(ps->font);
// distance visual
pd->graphics->fillRect(stroke, stroke, x-2*stroke, y-2*stroke, kColorBlack);
pd->graphics->drawLine(0, 0, x, y, stroke, kColorWhite);
pd->graphics->drawLine(x, 0, x, y, stroke, kColorBlack);
pd->graphics->drawLine(0, y, x, y, stroke, kColorBlack);
// distance message
pd->system->formatString(&message, "d=%.3f", fast_sqrt(x*x + y*y));
keepTextOnScreen(
&text_x, &text_y, (x - TEXT_WIDTH) / 2, (y - TEXT_HEIGHT) / 2
);
drawOutlinedText(
pd, message, text_x, text_y, stroke, kDrawModeInverted, kDrawModeCopy
);
// position message
pd->system->formatString(&message, "(%d, %d)", x, y);
keepTextOnScreen(&text_x, &text_y, x, y);
drawOutlinedText(
pd, message, text_x, text_y, stroke, kDrawModeCopy, kDrawModeInverted
);
// FPS display
pd->system->drawFPS(0,0);
// cleanup
pd->system->realloc(message, 0);
}Add main.h.
src/main.h
#ifndef MAIN_H
#define MAIN_H
#include "pd_api.h"
#define TEXT_WIDTH 86
#define TEXT_HEIGHT 16
extern const char* fontpath;
extern const LCDPattern gray50;
struct ProgramState {
PlaydateAPI *pd;
LCDFont *font;
PDButtons previousInput;
int strokeWidth;
int x;
int y;
int dx;
int dy;
};
void initProgramState(struct ProgramState *ps, PlaydateAPI *pd);
#ifdef _WINDLL
__declspec(dllexport)
#endif
int eventHandler(PlaydateAPI* pd, PDSystemEvent event, uint32_t arg);
static int update(void* userdata);
void handleInput(struct ProgramState *ps);
void draw(struct ProgramState *ps);
#endif // MAIN_HTake the fast_sqrt.f90 and fast_sqrt.h files from the previous section.
PREVIOUS_PROJECT_PATH="path_to_project_in_previous_section"
cp "${PREVIOUS_PROJECT_PATH}/fast_sqrt.f90" "${PREVIOUS_PROJECT_PATH}/fast_sqrt.h" src/Change the PRODUCT and SRC lines in the Makefile.
Makefile Partial Listing
PRODUCT = FortranTest.pdx
# List C source files here
SRC = src/main.c
# List Fortran source files here
FSRC = src/fast_sqrt.f90
# last line of Makefile
include common.mkPlaydate Makefiles rely on centralized machinery that does not support Fortran out of the box. Instead of directly modifying the original ${PLAYDATE_SDK_PATH}/C_API/buildsupport/common.mk file, make a copy of common.mk for this project.
cp "${PLAYDATE_SDK_PATH}/C_API/buildsupport/common.mk" common.mkUse the following diff as a guide to update common.mk.
$ diff "${PLAYDATE_SDK_PATH}/C_API/buildsupport/common.mk" common.mk
84c84
< _OBJS = $(SRC:.c=.o)
---
> _OBJS = $(SRC:.c=.o) $(FSRC:.f90=.o)
106a107,111
> SIMFC=$(shell which gfortran)
> SIMFCFLAGS = -gdwarf-2 -Wall
> FC=$(shell which $(TRGT)gfortran)
> FCFLAGS = $(MCFLAGS) $(OPT) -gdwarf-2 -Wall
>
131c136
< pdc: simulator
---
> pdc: device simulator
140a146,153
> $(OBJDIR)/%.o : %.f90 | OBJDIR DEPDIR
> mkdir -p `dirname $@`
> $(FC) $(FCFLAGS) -c $< -o $@
>
> $(OBJDIR)/%_simulator.o : %.f90 | OBJDIR DEPDIR
> mkdir -p $(dir $@)
> $(SIMFC) $(SIMFCFLAGS) -c $< -o $@
>
153,154c166,167
< $(OBJDIR)/pdex.${DYLIB_EXT}: OBJDIR
< $(SIMCOMPILER) $(DYLIB_FLAGS) -lm -DTARGET_SIMULATOR=1 -DTARGET_EXTENSION=1 $(INCDIR) -o $(OBJDIR)/pdex.${DYLIB_EXT} $(SRC)
---
> $(OBJDIR)/pdex.${DYLIB_EXT}: OBJDIR $(FSRC:%.f90=$(OBJDIR)/%_simulator.o)
> $(SIMCOMPILER) $(DYLIB_FLAGS) -lm -DTARGET_SIMULATOR=1 -DTARGET_EXTENSION=1 $(INCDIR) -o $(OBJDIR)/pdex.${DYLIB_EXT} $(SRC) $(FSRC:%.f90=$(OBJDIR)/%_simulator.o)Finally, build and run the project to verify it works. The square root demo should boot and run in the simulator.
PRODUCT="$(cat Source/pdxinfo | grep name | cut -d "=" -f 2-).pdx"
make clean simulator
pdc Source "${PRODUCT}"
playdate_simulator "${PRODUCT}"The Playdate SDK does not ship with arm-none-eabi-gfortran, but the full toolchain distributed by ARM includes it. Download the latest copy of the ARM toolchain for your host platfrom from the ARM GNU Toolchain Downloads Page, and install it. The author of this post downloaded the macOS Hosted Bare-Metal Target (arm-none-eabi) 11.3.rel1 toolchain.
The toolchain was installed in /Applications/ArmGNUToolchain/ on macOS, The following command can be used to find the installation directory from the command line.
dirname $(find / -name "arm-none-eabi-gfortran" 2>/dev/null)Add the directory to the PATH environment variable.
ARM_TOOLCHAIN_PATH="/Applications/ArmGNUToolchain/11.3.rel1/arm-none-eabi/bin"
echo 'export PATH="'"${ARM_TOOLCHAIN_PATH}"':${PATH}"' >> "${HOME}/.profile"Reload .profile if necessary.
source "${HOME}/.profile"The above diff contains all of the necessary changes to build a PDX file that runs on hardware. After updating the PATH, build and run the program to verify it works. To upload a PDX file to hardware, first run it in the simulator.
PRODUCT="$(cat Source/pdxinfo | grep name | cut -d "=" -f 2-).pdx"
make
playdate_simulator "${PRODUCT}"Then either “Upload Game to Device” from the “Device” menu or Playdate icon on the lower lefthand corner of the simulator (with the crank controls collapsed). Once the game is on the device, pdutil can launch it.
# after the game is on the device
PRODUCT="$(cat Source/pdxinfo | grep name | cut -d "=" -f 2-).pdx"
PDUTIL_DEVICE="$(ls /dev/cu.usbmodemPD* | head -n 1)"
pdutil "${PDUTIL_DEVICE}" run "/Games/${PRODUCT}"Pull out the crank and use the D-pad to move the lower righthand point to (300, 125). The diagonal length should be 325.000. Use a calculator to verify other sets of values.
300 * 300 = 90000
125 * 125 = 15625
325 * 325 = 105625
----------------------
90000 + 15625 = 105625The Fortran quickstart tutorial has a section on Derived Types. Specifically, bind(c) offers interoperability with the C programming language. gcc also has documention on Fortran interoperability with C.
This post is based on the “Fortran on Playdate?” thread on the Playdate Developer Forums.
The Panic Playdate is a tiny, just-for-fun indie game console. This post will discuss getting started with ASM on the Panic Playdate. The Playdate’s CPU is a Cortex M7 that only supports Thumb instructions. The simulator uses the instruction set of the development machine. The author has tested ASM in versions of the simulator that run on both X86_64 and Apple Silicon.
$ date -u "+%Y-%m-%d %H:%M:%S +0000"
2022-10-05 19:28:00 +0000
$ uname -vm
Darwin Kernel Version 21.6.0: Mon Aug 22 20:19:52 PDT 2022; root:xnu-8020.140.49~2/RELEASE_ARM64_T6000 arm64
$ ex -s +'%s/<[^>].\{-}>//ge' +'%s/\s\+//e' +'%norm J' +'g/^$/d' +%p +q! /System/Library/CoreServices/SystemVersion.plist | grep -E 'ProductName|ProductVersion' | sed 's/^[^ ]* //g' | sed 'N; s/\n/ /g'
macOS 12.6
$ sysctl -n machdep.cpu.brand_string
Apple M1 Max
$ echo "${SHELL}"
/bin/bash
$ "${SHELL}" --version | head -n 1
GNU bash, version 3.2.57(1)-release (arm64-apple-darwin21)
$ cat "${HOME}/Developer/PlaydateSDK/VERSION.txt"
1.12.3
$ cargo --version
cargo 1.66.0-nightly (f5fed93ba 2022-09-27)When ASM is handwritten at all, it is generally used for optimizing native code. Therefore, the Hello World C API example will make a reasonable project template.
# copy in project template
PROJECT="asm_test"
PROJECT_PATH="my_playdate_projects"
cd "${PROJECT_PATH}"
cp -r "${PLAYDATE_SDK_PATH}/C_API/Examples/Hello World/" "${PROJECT}"
cd "${PROJECT}"Replace the contents of main.c with the following. This program calculates the distance of a diagonal line according to the Pythagorean theorem. The bulk of the code is C, but the square root will be calculated in ASM. Note that the D-pad, buttons, and crank can be used to control the distance in different ways.
src/main.c
#include "fast_sqrt.h"
#include "main.h"
#include "pd_api.h"
const char* fontpath = "/System/Fonts/Asheville-Sans-14-Bold.pft";
const LCDPattern gray50 = {
// Bitmap
0b10101010,
0b01010101,
0b10101010,
0b01010101,
0b10101010,
0b01010101,
0b10101010,
0b01010101,
// Mask
0b11111111,
0b11111111,
0b11111111,
0b11111111,
0b11111111,
0b11111111,
0b11111111,
0b11111111,
};
void initProgramState(struct ProgramState *ps, PlaydateAPI *pd)
{
const char *errorMessage;
ps->pd = pd;
ps->font = NULL;
ps->font = pd->graphics->loadFont(fontpath, &errorMessage);
if (NULL == ps->font) {
pd->system->error("%s:%i Couldn't load font %s: %s",
__FILE__, __LINE__, fontpath, errorMessage
);
}
ps->previousInput = 0;
ps->strokeWidth = 2;
ps->x = (LCD_COLUMNS - TEXT_WIDTH) / 2;
ps->y = (LCD_ROWS - TEXT_HEIGHT) / 2;
ps->dx = 1;
ps->dy = 1;
}
#ifdef _WINDLL
__declspec(dllexport)
#endif
int eventHandler(PlaydateAPI* pd, PDSystemEvent event, uint32_t arg)
{
(void)arg; // only used for kEventKeyPressed == event
static struct ProgramState *ps = NULL;
switch (event) {
case kEventInit:
ps = pd->system->realloc(ps, sizeof(struct ProgramState));
initProgramState(ps, pd);
pd->system->setUpdateCallback(update, (void *)ps);
break;
case kEventTerminate:
pd->system->realloc(ps, 0);
ps = NULL;
break;
default:
// do nothing
break;
};
return 0;
}
static int update(void* userdata)
{
struct ProgramState *ps = (struct ProgramState *)userdata;
handleInput(ps);
draw(ps);
return 1;
}
void handleInput(struct ProgramState *ps) {
PlaydateAPI* pd = ps->pd;
int x_direction = 0;
int y_direction = 0;
// dpad input
PDButtons currentInput;
pd->system->getButtonState(¤tInput, NULL, NULL);
if ( currentInput & kButtonUp ) {
ps->y--;
} else if ( currentInput & kButtonDown ) {
ps->y++;
} else {
y_direction = 1;
}
if ( currentInput & kButtonLeft ) {
ps->x--;
} else if ( currentInput & kButtonRight ) {
ps->x++;
} else {
x_direction = 1;
}
if (( currentInput & kButtonA ) && !( ps->previousInput & kButtonA )) {
ps->dx *= -1;
}
if (( currentInput & kButtonB ) && !( ps->previousInput & kButtonB )) {
ps->dy *= -1;
}
ps->previousInput = currentInput;
int steps;
if (pd->system->isCrankDocked()) {
steps = 1;
} else {
steps = pd->system->getCrankChange();
if (steps < 0) {
steps = -steps;
x_direction = -1;
y_direction = -1;
}
}
for (int i = 0; i < steps; i++) {
ps->x += ps->dx * x_direction;
ps->y += ps->dy * y_direction;
// bounce
if ( ps->x < 0 || LCD_COLUMNS < ps->x ) {
ps->dx *= -1;
}
if ( ps->y < 0 || LCD_ROWS < ps->y ) {
ps->dy *= -1;
}
}
}
int adjustTextPosition(int x, int w, int min, int max) {
if (x < min) {
return min;
} else if (max < x + w) {
return max - w;
} // else
return x;
}
void keepTextOnScreen(int *x_ptr, int *y_ptr, int x, int y) {
*x_ptr = adjustTextPosition(x, TEXT_WIDTH, 0, LCD_COLUMNS);
*y_ptr = adjustTextPosition(y, TEXT_HEIGHT, 0, LCD_ROWS);
}
void drawOutlinedText(
PlaydateAPI* pd,
const char *message,
int x,
int y,
int outlineWidth,
LCDColor textColor,
LCDColor outlineColor
) {
pd->graphics->setDrawMode(outlineColor);
pd->graphics->drawText(
message, strlen(message), kASCIIEncoding, x - outlineWidth, y
);
pd->graphics->drawText(
message, strlen(message), kASCIIEncoding, x + outlineWidth, y
);
pd->graphics->drawText(
message, strlen(message), kASCIIEncoding, x, y - outlineWidth
);
pd->graphics->drawText(
message, strlen(message), kASCIIEncoding, x, y + outlineWidth
);
pd->graphics->setDrawMode(textColor);
pd->graphics->drawText(message, strlen(message), kASCIIEncoding, x, y);
}
void draw(struct ProgramState *ps)
{
PlaydateAPI* pd = ps->pd;
int stroke = ps->strokeWidth;;
int x = ps->x;
int y = ps->y;
char *message = NULL;
int text_x, text_y;
pd->graphics->clear((LCDColor)gray50);
pd->graphics->setFont(ps->font);
// distance visual
pd->graphics->fillRect(stroke, stroke, x-2*stroke, y-2*stroke, kColorBlack);
pd->graphics->drawLine(0, 0, x, y, stroke, kColorWhite);
pd->graphics->drawLine(x, 0, x, y, stroke, kColorBlack);
pd->graphics->drawLine(0, y, x, y, stroke, kColorBlack);
// distance message
pd->system->formatString(&message, "d=%.3f", fast_sqrt(x*x + y*y));
keepTextOnScreen(
&text_x, &text_y, (x - TEXT_WIDTH) / 2, (y - TEXT_HEIGHT) / 2
);
drawOutlinedText(
pd, message, text_x, text_y, stroke, kDrawModeInverted, kDrawModeCopy
);
// position message
pd->system->formatString(&message, "(%d, %d)", x, y);
keepTextOnScreen(&text_x, &text_y, x, y);
drawOutlinedText(
pd, message, text_x, text_y, stroke, kDrawModeCopy, kDrawModeInverted
);
// FPS display
pd->system->drawFPS(0,0);
// cleanup
pd->system->realloc(message, 0);
}Add main.h.
src/main.h
#ifndef MAIN_H
#define MAIN_H
#include "pd_api.h"
#define TEXT_WIDTH 86
#define TEXT_HEIGHT 16
extern const char* fontpath;
extern const LCDPattern gray50;
struct ProgramState {
PlaydateAPI *pd;
LCDFont *font;
PDButtons previousInput;
int strokeWidth;
int x;
int y;
int dx;
int dy;
};
void initProgramState(struct ProgramState *ps, PlaydateAPI *pd);
#ifdef _WINDLL
__declspec(dllexport)
#endif
int eventHandler(PlaydateAPI* pd, PDSystemEvent event, uint32_t arg);
static int update(void* userdata);
void handleInput(struct ProgramState *ps);
void draw(struct ProgramState *ps);
#endif // MAIN_HAdd the fast_sqrt.h header file for the ASM code.
src/fast_sqrt.h
#ifndef FAST_SQRT_H
#define FAST_SQRT_H
extern float fast_sqrt(float);
#endif // FAST_SQRT_HAdd a stub fast_sqrt.c implementation.
#include "fast_sqrt.h"
float fast_sqrt(float x) {
// non-functional stub
return 0.0;
}Change the PRODUCT and SRC lines in the Makefile.
Makefile Partial Listing
PRODUCT = ASMTest.pdx
SRC = src/main.c src/fast_sqrt.cUpdate pdxinfo.
Source/pdxinfo
name=ASMTest
author=Brendan Sechter
description=ASM on Playdate proof of concept.
bundleID=com.sennue.poc_asmtest
imagePath=Finally, build and run the project to make sure it works.
PRODUCT="$(cat Source/pdxinfo | grep name | cut -d "=" -f 2-).pdx"
make
playdate_simulator "${PRODUCT}"The distance of the diagonal line should be a fixed value of 0.0. The goal is to calculate that value with ASM.
On modern CPUs, calculating the square root of a number can be done with a single instruction. The Cortex M7 uses the ARMv7E-M microarchitecture. It only supports Thumb instructions. ARM-Thumb interworking is not possible on the Playdate.
The Thumb ASM for a square root subroutine that will run on hardware follows.
src/fast_sqrt_armv7.s
.syntax unified
.set ALIGNMENT, 4
.text
.align ALIGNMENT
.global fast_sqrt
fast_sqrt:
vsqrt.f32 s0, s0
bx lrThe MacBook Pro this post is being typed up on runs on an Apple M1 Max. It uses the ARMv8.5-A instruction set. The Apple Silicon cores only support 64-bit ARM instructions. Thumb is a thing of the past, and 32-bit ARM instructions are not supported either.
The ARMv8 ASM for a square root subroutine that will run on the simulator follows.
src/fast_sqrt_armv8.s
.set ALIGNMENT, 8
.text
.align ALIGNMENT
.global _fast_sqrt
_fast_sqrt:
fsqrt s0, s0
retThe author first experimented with ASM on Playdate using a machine that runs x86-64 instructions. This is the ASM for a simulator subroutine that runs on a 64-bit Intel processor.
src/fast_sqrt_x86_64.s
.intel_syntax
.set ALIGNMENT, 16
.text
.global _fast_sqrt
_fast_sqrt:
sqrtss xmm0, xmm0
retThe Playdate Makefiles look like they were written with ASM, but a few modifications need to be made to properly build the project. First, the ASM for the device and simulator need to be listed separately. Update SRC and add ASRC definitions in the Makefile. Uncomment the ASRC_SIMULATOR definition for your development platform. Also, update the last line of the Makefile for the next step.
Makefile
# List C source files here
SRC = src/main.c
# List ASM source files here
# Uncomment the ASRC_SIMULATOR definition for your development platform.
ASRC_DEVICE = src/fast_sqrt_armv7.s
#ASRC_SIMULATOR = src/fast_sqrt_armv8.s
#ASRC_SIMULATOR = src/fast_sqrt_x86_64.s
# last line of Makefile
include common.mkPlaydate Makefiles rely on some common machinery that does not entirely support ASM code. The ${PLAYDATE_SDK_PATH}/C_API/buildsupport/common.mk file could be modified directly, but it is better to keep the modified copy in the project. Copy common.mk into the project.
cp "${PLAYDATE_SDK_PATH}/C_API/buildsupport/common.mk" common.mkThree modifications need to be made to the local common.mk. ASRC_DEVICE needs to be appended to _OBJS, and ASRC_SIMULATOR needs to be appended to the $(OBJDIR)/pdex.${DYLIB_EXT} target. Finally, the pdc target needs to rely on the device so that a functional copy of pdex.bin is always included in the “fat” PDX file. (Hardware runs pdex.bin while the simulator uses a dynamic library, pdex.dylib on macOS.)
The following diff gives a guide to the changes that need to be made to common.mk.
$ diff "${PLAYDATE_SDK_PATH}/C_API/buildsupport/common.mk" common.mk
84c84
< _OBJS = $(SRC:.c=.o)
---
> _OBJS = $(SRC:.c=.o) $(ASRC_DEVICE:.s=.o)
131c131
< pdc: simulator
---
> pdc: device simulator
154c154
< $(SIMCOMPILER) $(DYLIB_FLAGS) -lm -DTARGET_SIMULATOR=1 -DTARGET_EXTENSION=1 $(INCDIR) -o $(OBJDIR)/pdex.${DYLIB_EXT} $(SRC)
---
> $(SIMCOMPILER) $(DYLIB_FLAGS) -lm -DTARGET_SIMULATOR=1 -DTARGET_EXTENSION=1 $(INCDIR) -o $(OBJDIR)/pdex.${DYLIB_EXT} $(SRC) $(ASRC_SIMULATOR)Rebuild the project. If all goes well, the diagonal distance should be calculated and updated in realtime. The program will automatically resize the rectangle if the crank is docked. Undock the crank for manual control and verification.
PRODUCT="$(cat Source/pdxinfo | grep name | cut -d "=" -f 2-).pdx"
make
playdate_simulator "${PRODUCT}"To upload a PDX file to hardware, first, run it in the simulator. Then either “Upload Game to Device” from the “Device” menu or Playdate icon on the lower lefthand corner of the simulator (with the crank controls collapsed). Once the game is on the device, pdutil can be used to launch it.
# after the game is on the device
PRODUCT="$(cat Source/pdxinfo | grep name | cut -d "=" -f 2-).pdx"
PDUTIL_DEVICE="$(ls /dev/cu.usbmodemPD* | head -n 1)"
pdutil "${PDUTIL_DEVICE}" run "/Games/${PRODUCT}"Alternatively, pdutil can be used to directly upload the game to hardware from the command line. Note that the author could not get the following code to reliably work in a script because it takes time for the Playdate to become available after it is mounted in datadisk mode.
PDUTIL_DEVICE="$(ls /dev/cu.usbmodemPD* | head -n 1)"
PRODUCT="$(cat Source/pdxinfo | grep name | cut -d "=" -f 2-).pdx"
DEVICE_PRODUCT_PATH="/Volumes/PLAYDATE/Games/${PRODUCT}"
make device
pdc Source "${PRODUCT}"
pdutil "${PDUTIL_DEVICE}" datadisk
# it may take time for the device to become available
cp -r "${PRODUCT}" "${DEVICE_PRODUCT_PATH}"
MOUNT_DEVICE="$(diskutil list | grep PLAYDATE | grep -oE '[^ ]+$')"
diskutil unmount "${MOUNT_DEVICE}"
# press "A" to get the Playdate out of datadisk modePull out the crank and use the D-pad to move the lower righthand point to (100, 75). The diagonal length should be 125.000. Use a calculator to verify other sets of values.
100 * 100 = 10000
75 * 75 = 5625
125 * 125 = 15625
--------------------
10000 + 5625 = 15625The ARM Cortext-M7 Processor Technical Reference Manual gives detailed information on the processor used in the Playdate. Instruction references for ARM+Thumb ASM, 64-bit ARM ASM, and X86+AMD64 ASM may be useful.
This post is based on the “Adding ASM .s file to a project” thread on the Playdate Developer Forums.
The Panic Playdate is a tiny, just-for-fun indie game console. Rust is a drop-in replacement for C that is fast and memory safe. This post will discuss getting started with the Panic Playdate using Rust. It is a follow-up to my post on getting started with Playdate.
crank and crankstart will be used because they are working, existing solutions for using Rust to develop applications for the Playdate. The post will cover installation, running examples, as well as building and running a couple of existing crankstart projects: Klondike solitaire, and Nine Lives.
Familiarity with Rust and the command line are assumed. It is also assumed that the Playdate SDK has already been installed from the Playdate Developer Page and that Rust has been installed with rustup.
$ date -u "+%Y-%m-%d %H:%M:%S +0000"
2022-10-04 18:23:42 +0000
$ uname -vm
Darwin Kernel Version 21.6.0: Mon Aug 22 20:19:52 PDT 2022; root:xnu-8020.140.49~2/RELEASE_ARM64_T6000 arm64
$ ex -s +'%s/<[^>].\{-}>//ge' +'%s/\s\+//e' +'%norm J' +'g/^$/d' +%p +q! /System/Library/CoreServices/SystemVersion.plist | grep -E 'ProductName|ProductVersion' | sed 's/^[^ ]* //g' | sed 'N; s/\n/ /g'
macOS 12.6
$ echo "${SHELL}"
/bin/bash
$ "${SHELL}" --version
GNU bash, version 3.2.57(1)-release (arm64-apple-darwin21)
Copyright (C) 2007 Free Software Foundation, Inc.
$ cat "${HOME}/Developer/PlaydateSDK/VERSION.txt"
1.12.3
$ cargo --version
cargo 1.66.0-nightly (f5fed93ba 2022-09-27)First, install crank according to the README.
PROJECT_PATH="my_playdate_projects"
cd "${PROJECT_PATH}"
git clone git@github.com:pd-rs/crank.git
cd crank
cargo install --path . --forceNext, clone the crankstart repository to run the examples.
PROJECT_PATH="my_playdate_projects"
cd "${PROJECT_PATH}"
git clone git@github.com:pd-rs/crankstart.gitThe hello_world and life examples can simply be run.
PROJECT="crankstart"
PROJECT_PATH="my_playdate_projects"
cd "${PROJECT_PATH}/${PROJECT}"
EXAMPLE="hello_world"
crank run --release --example "${EXAMPLE}"
EXAMPLE="life"
crank run --release --example "${EXAMPLE}"Assets from the C_API need to be copied in before running the sprite_game example.
cp -a "${PLAYDATE_SDK_PATH}/C_API/Examples/Sprite Game/Source/images/." sprite_game_images
EXAMPLE="sprite_game"
crank run --release --example "${EXAMPLE}"The author of crank and crankstart wrote a Klondike solitaire game in Rust. Use the following commands to build and run it.
PROJECT_PATH="my_playdate_projects"
cd "${PROJECT_PATH}"
git clone git@github.com:pd-rs/crankstart-klondike.git
cd crankstart-klondike
crank run --releaseA third party, bravely, wrote the Nine Lives game in Rust. It can be built and run as follows.
PROJECT_PATH="my_playdate_projects"
cd "${PROJECT_PATH}"
git clone git@github.com:bravely/nine_lives.git
cd nine_lives
crank run --releasecargo-xbuild is required to build for hardware.
cargo install cargo-xbuildxbuild requires source to be installed, so it needs to be installed with rustup.
rustup component add rust-srcThe build subcommand takes a –device flag that can be used to target hardware exclusively. Alternatively, the package subcommand can be used to build binaries for both the device and the simulator. To upload a PDX file to hardware, first, run it in the simulator. Then either “Upload Game to Device” from the “Device” menu or Playdate icon on the lower lefthand corner of the simulator (with the crank controls collapsed). Once the game is on the device, pdutil can be used to launch it.
# example (build)
EXAMPLE="life"
PDX_FILE="Life"
PROJECT="crankstart"
PROJECT_PATH="my_playdate_projects"
cd "${PROJECT_PATH}/${PROJECT}"
crank build --device --release --example "${EXAMPLE}"
playdate_simulator "target/${PDX_FILE}.pdx"
# from simulator: "Device > Upload Game to Device
# once game is on devce
pdutil /dev/cu.usbmodemPD* run "/Games/${PDX_FILE}.pdx"
# example (package)
EXAMPLE="hello_world"
PDX_FILE="Hello World"
crank package --example "${EXAMPLE}"
playdate_simulator "target/${PDX_FILE}.pdx"
# from simulator: "Device > Upload Game to Device
# once game is on devce
pdutil /dev/cu.usbmodemPD* run "/Games/${PDX_FILE}.pdx"
# project (build)
PROJECT="crankstart-klondike"
PDX_FILE="Klondike"
PROJECT_PATH="my_playdate_projects"
cd "${PROJECT_PATH}/${PROJECT}"
crank build --device --release
playdate_simulator "target/${PDX_FILE}.pdx"
# from simulator: "Device" > "Upload Game to Device"
# once game is on devce
pdutil /dev/cu.usbmodemPD* run "/Games/${PDX_FILE}.pdx"
# project (package)
PROJECT="nine_lives"
PDX_FILE="Nine Lives"
PROJECT_PATH="my_playdate_projects"
cd "${PROJECT_PATH}/${PROJECT}"
crank package
playdate_simulator "target/${PDX_FILE}.pdx"
# from simulator: "Device" > "Upload Game to Device"
# once game is on devce
pdutil /dev/cu.usbmodemPD* run "/Games/${PDX_FILE}.pdx"The run subcommand should work like the build subcommand, but it is not working on the author’s machice in the latest version of the SDK. The latest version of the SDK also seems to have trouble booting PDX files with spaces in the filename using the simulator and pdutil, but the game can be launched on the device after it has been uploaded.
# example
EXAMPLE="sprite_game"
PROJECT="crankstart"
PROJECT_PATH="my_playdate_projects"
cd "${PROJECT_PATH}/${PROJECT}"
crank run --device --release --example "${EXAMPLE}"
# project
PROJECT="nine_lives"
PROJECT_PATH="my_playdate_projects"
cd "${PROJECT_PATH}/${PROJECT}"
crank run --device --releaseNote that the Playdate C API documentation (and to a lesser extent, the Lua documentation) are useful when developing applications in Rust. This post is based on the Rust development thread from the Playdate Developer Forum.
The Panic Playdate is a tiny, just-for-fun indie game console. This post will discuss getting started with the Panic Playdate. It will cover downloading the SDK, installing it, and running the examples. macOS will be used, but the steps should be largely the same for other platforms. This post assumes familiarity with the command line.
Note that command line familiarity is not needed for Playdate development. Downloading the SDK is enough to get started if Pulp is sufficient for your needs. For most developers, Lua knowledge and a Playdate-integrated editor, like Nova (link to Playdate Extensions), will be enough to make their Playdate development dreams come true. (Dedication to see a project to completion is also required.)
$ date -u "+%Y-%m-%d %H:%M:%S +0000"
2022-10-03 20:21:04 +0000
$ uname -vm
Darwin Kernel Version 21.6.0: Mon Aug 22 20:19:52 PDT 2022; root:xnu-8020.140.49~2/RELEASE_ARM64_T6000 arm64
$ ex -s +'%s/<[^>].\{-}>//ge' +'%s/\s\+//e' +'%norm J' +'g/^$/d' +%p +q! /System/Library/CoreServices/SystemVersion.plist | grep -E 'ProductName|ProductVersion' | sed 's/^[^ ]* //g' | sed 'N; s/\n/ /g'
macOS 12.6
$ echo "${SHELL}"
/bin/bash
$ "${SHELL}" --version
GNU bash, version 3.2.57(1)-release (arm64-apple-darwin21)
Copyright (C) 2007 Free Software Foundation, Inc.
$ cat "${HOME}/Developer/PlaydateSDK/VERSION.txt"
1.12.3First, download the latest Playdate SDK (link to all versions) from the Playdate Developer Page. Update the path, set the SDK path, and consider adding an alias for the Playdate simulator.
# update path
echo 'export PATH="${HOME}/Developer/PlaydateSDK/bin:${PATH}"' >> "${HOME}/.profile"
# set the Playdate SDK path
echo 'export PLAYDATE_SDK_PATH="${HOME}/Developer/PlaydateSDK"' >> "${HOME}/.bash_profile"
# add alias for simulator
echo 'alias playdate_simulator="open ${HOME}/Developer/PlaydateSDK/bin/Playdate\ Simulator.app"' >> "${HOME}/.bash_profile"
# reload profiles, if necessary
. "${HOME}/.profile"
. "${HOME}/.bash_profile"Pulp is a web-based game editor for the Playdate. The target audience is entry-level game developers and people who want to rapidly prototype. All development and testing can be done in the browser. Pulp has a lot of limitations, but it is also easy to learn! (Links to documentation for Pulp and PulpScript.) Pulp is a good choice for people who are not ready to learn to program.
Entire games can be exported and imported in JSON format. To run a game developed with Pulp in the simulator, click the “DOWNLOAD PDX” button, and then pass the PDX file to the simulator.
GAME="my-game"
GAME_PATH="${HOME}/Downloads"
playdate_simulator "${GAME_PATH}/${GAME}.pdx"The Lua scripting language can also be used to develop Playdate games. The target audience is moderately sophisticated developers. Lua is a popular scripting language commonly used in game development, and the Lua API is not as restricted as Pulp’s web-based development model. (Link to Lua documentation.) Lua is generally the best choice for projects with a programmer.
Regular project-based Lua examples can be run as follows.
# cd to location of examples directory
cd "${HOME}/Developer/PlaydateSDK/Examples/"
# run the "2020" exmaple
EXAMPLE="2020"
pdc "${EXAMPLE}/Source" "${EXAMPLE}.pdx"
playdate_simulator "${EXAMPLE}".pdx
# cleanup file when no longer needed
rm -rf "${EXAMPLE}.pdx"Single file Lua examples can be run as follows.
# cd to location of examples directory
cd "${HOME}/Developer/PlaydateSDK/Examples/"
# run the "animator" exmaple
EXAMPLE="animator"
pdc -m "Single File Examples/${EXAMPLE}.lua" "${EXAMPLE}.pdx"
playdate_simulator "${EXAMPLE}.pdx"
# cleanup file when no longer needed
rm -rf "${EXAMPLE}.pdx"Sophisticated developers can use the C API to make software for the Playdate. Many professional AAA game developers use C++, but C is the language they used in the past. (Link to C API documentation.) Only use the C API if you know why you need to use it.
The C API examples can be run as follows.
# cd to location of examples directory
cd "${HOME}/Developer/PlaydateSDK/C_API/Examples/"
# run the "3D library" exmaple
EXAMPLE="3D library"
(cd "./${EXAMPLE}"; make; playdate_simulator *.pdx)
# cleanup file when no longer needed
(cd "./${EXAMPLE}"; make clean)Consider visiting the Playdate Developer Page and Playdate Developer Forums for more information!