Proposed API Updates (January 2023)

[bvanvugt]

Proposed API Changes (January 2023)

As part of our move to competitive Leaderboards we're proposing the following updates to the Battlesnake API.

This post and design brief serves as a discussion point for community feedback.

1. Allow Maps to indicate when Food and Hazards will be automatically removed

We'd like to encourage more Maps that remove Food and Hazards as part of their core mechanics. Ideally this is communicated to Battlesnakes in advance, to avoid the frustration of Food randomly disappearing.

We propose adding a ttl property ("turns to live") to Food and Hazard objects.

{
    "board": {
        "food": [
            {"x": 8, "y": 0, "ttl": 5},
            {"x": 5, "y": 5, "ttl": 10},
            {"x": 1, "y": 9, "ttl": 0}
        ],
        "hazards": [
            {"x": 9, "y": 2, "ttl": 99},
            {"x": 9, "y": 1, "ttl": 98},
            {"x": 9, "y": 0, "ttl": 97}
        ]
    }
}

Questions and Considerations

What about food and hazards that will never be removed automatically?

This is a required use case, in order to support the current Map behavior. This design document proposes that in thoses cases, the ttl property is omitted entirely (rather than setting it to null or some other special value), making this new property optional.

Are objects removed when ttl is 1 or 0?

Removing after ttl is 0 seems to make the most sense.

This is best stated by @coreyja: "Objects with a ttl of 0 will NOT be on the board next turn".

What happens if a Battlesnake moves on to Food/Hazard the same turn it's removed?

The current engine allows Battlesnakes to consume food on turns their health would naturally reach zero. This sets an interesting precedent of siding in the favor of the Battlesnake in these situations, and likely one that we should continue.

@chillfox stated this as: "Once you take the greater context into account it's consistent to always 'lean' in favor of the snake."

For those reasons, we're proposing the following:

• Consuming food on turns following it's TTL being 0 will heal the Battlesnake as per normal food consumption.
• Entering a Hazard on turns following it's TTL being 0 will NOT deal additional damage.

2. Allow Maps to vary the amount healed and damage received by individual Food and Hazards.

In 2022 we experimented heavily with stacked Hazards (placing multiple Hazards on the same location, causing an increase in damage for that particular square). The results were a lot of fun, and since then we've heard a few awesome Map ideas that would expand on this.

One reasonable concern about this approach is that it means Hazard and Food coordinates are not unique on the board, meaning API requests could potentially be of unbounded size. This is not great for highly optimized Battlesnakes.

Rather than encourage object stacking, we'd like to propose adding variability to individual Food and Hazards in the form of new properties for each.

Food.heal will indicate the maximum amount of health restored by consuming this particular food.

Hazard.damage will indicate the amount of additional damage received by entering this location.

Examples:

{
    "board": {
        "food": [
            {"x": 8, "y": 0, "heal": 100},
            {"x": 5, "y": 5, "heal": 5},
            {"x": 1, "y": 9, "heal": 25}
        ],
        "hazards": [
            {"x": 9, "y": 2, "damage": 14},
            {"x": 9, "y": 1, "damage": 14},
            {"x": 9, "y": 0, "damage": 100}
        ]
    }
}

It's generally expected that these values will not change over the lifetime of the object on the game board, however this will ultimately be up to the Map to decide. There may be particularly interesting use cases for Maps that modify this value between turns, such as Food or Hazards that decay over time.

Questions and Considerations

Are these properties optional?

No, it's proposed that these properties will be required on all Food and Hazard definitions. The alternative would require some additional global default being set and subsequently read and applied by Battlesnakes, which is more cumbersome and error-prone than just making it a required property.

Why Food.heal and Hazard.damage?

We had considered something more generic, such as value, that would allow both object types to be parsed by the same definition. One reason to not take that approach is that these objects may naturally diverge over time and we'd be okay with that. Another is something generic like value still requires interpretation.

Ultimately we prefered the semantic value and readability provided by context-specific heal and damage.

Can these values be negative? What about zero?

Sure! Why not. It's easy enough to code for on both the engine and Battlesnake side, and could open doors for creative Maps in the future.

How is the current behavior represented (food always heals to full)?

To start, we'll use the max health value to indicate fodo that heals Battlesnakes to full. This follows the healing algorithm of snake.health = max(snake.health + food.heal, MAX_HEALTH). In the future we could provide the maximum health value as a game configuration property.

3. Replace game.ruleset with a new game.rules object

Battlesnake "rulesets" are a legacy concept that are no longer used by the game engine (which is now based on Maps and pipelines). Additionally, over time the ruleset object has been expanded rather hap-hazardly.

We propose replacing it with something more appropriate.

Current Behavior

A lot of these properties are deprecated, now controlled by individual Maps.

{
    "game": {
        "ruleset": {
            "name": "standard",
            "version": "v1.2.1",
            "settings": {
                "foodSpawnChance": 15,
                "minimumFood": 1,
                "hazardDamagePerTurn": 0,
                "hazardMap": "",
                "hazardMapAuthor": "",
                "royale": {
                    "shrinkEveryNTurns": 0
                },
                "squad": {
                    "allowBodyCollisions": false,
                    "sharedElimination": false,
                    "sharedHealth": false,
                    "sharedLength": false
                }
            }
        }
    }
}

Proposed Behavior

A new game.rules object that holds configuration coming from the game rules (rather than the Map). Note that we'd call it rules and not ruleset in an effort to match the rules repo name.

Beyond version information, we don't have much else to add to this object right now.

{
    "game": {
        "rules": {
            "version": "v1.2.1"
        }
    }
}

Open Questions

• Maybe out of bounds handling should be specified here too, since it's relevant to all games (eliminated vs. wrapped etc.)

4. Convert game.map from a string to an object

Maps are the future. Over time we'd like to push more game control into Map definitions, including out of bounds handling, food and hazard ttls, and even special elimination conditions. Eventually challenges could/will be written as Maps as well.

Providing more Map-specific information in the API is going to become increasingly important. Right now this information is provided rather hap-hazardly as part of the games.ruleset object (see above), and map is simply a string id. We'd like to change this to support additional Map meta information.

Current Behavior

Map information is constrained to a single string identifier.

{
    "game": {
        "map": "standard"
    }
}

Proposed Behavior

Convert game.map into an object that includes metadata about the Map and its configuration for this particular game.

{
    "game": {
        "map": {
            "id": "standard",
            "author": "Battlesnake",
            "version": "1",
            "settings": {
                "minimumFood": 1,
                "foodSpawnChance": 15
            }
        }
    }
}

{
    "game": {
        "map": {
            "id": "royale",
            "author": "Battlesnake",
            "version": "1",
            "settings": {
                "shrinkEveryNTurns": 25
            }
        }
    }
}

Open Questions

• Is map.author actually useful here?
• Any value in adding a map.name?

5. Do these changes warrant a new API version?

Technically all proposed changes are additive (and most likely non-breaking), with the one exception of game.map becoming an object instead of a string. Does this warrant a full version bump?

If so, this would be the first major bump we've done during active play. How do we handle API version "1"?

[coreyja]

Copying my comments over from the gist

Chatted through this with myself on Stream! Leaving my notes here, but I will try to add a link to the VOD when I finish streaming!
https://www.twitch.tv/videos/1722192261

Corey's Thoughts: Proposed Battlesnake API Changes Jan 2023

1. TTL for Food and Hazard

• Is the ttl property required? What does it mean if not present?
  • Not Required. But required and null-able is reasonable as well
    • If the key is present it should have a non-null non-negative integer value
    • A missing key means indefinite TTL
• How should indefinite placement be represented?
  • Either a missing key, or a null value
  • I'd prefer that over a 'magic number' like -1
• Are objects removed when ttl is 1 or 0?
  • Objects with a TTL of 0, will NOT be on the board next turn
  • I think this matches semantically with the "Turns to Live", if an object still has 1 turn to live it feels like it should make it to the next board? No strong feels though
• What happens if a Battlesnake moves onto Food the same turn it's removed?
  • 🤷 I think we just decide a turn resolution order and enforce it.
  • I guess I think eating BEFORE food is removed seems like it ideally should eat it. Kinda how eating a food in hazard keeps you alive
  • But on the other hand, it feels like maybe a hazard SHOULDN'T damage you on the same turn its removed... Is that inconsistency weird?
  • I think I'd rather this be consistent for food and hazards. Less preference on before vs after
    • The most "natural" to me seems to be the one that is 'safest' for the snake. Which is food gets counted and hazards don't. But I think the difference in object types there might be confusing without a big benefit

2. Allow maps to vary the amount healed and damage received by individual Food and Hazards.

• Are these properties optional? If so, what does it mean if they're not present?
  • I don't think they need to be optional. Don't see a huge benefit to not always sending them
  • If they are optional, some default in the 'rules' object probably makes sense
• Is value the best name here? What about Food.heal and/or Hazard.damage?
  • 'value' is nice in that I can use the same Type for both food and Hazard parsing...
  • But I think I like the semantic value of of "damage" and "heal"
    • I think there is more benefit in the semantic value and being able to guess at their usage from reading the JSON, than to use the same type for parsing
• Can these values be negative? (could be fun)
  • Yup!
    • Why not 🤷 lol
• How do we codify the current behavior of "food heals to full"?
  • Not sure I feel anything needs to change? Maybe just an explicit callout in the docs page if its not present already?
  • I guess you could send a 'max_health' field in the 'rules' (or any) object if you don't want to rely on max_health always being 100
• These values would be immutable for the lifetime of the object.
  • Is the benefit predictability? Seems likely
  • I like predictability, but it does limit "map makers" not to have changing values. For instance food that 'rots' and decays overtime could be interesting!
    • Stacking hazards like let us do the same for hazards, where over time we could adjust the stack count. For instance Snail Mode uses (or did in a prototype) to alter the damage over time
  • Feels hard to guarantee in code

3. Replace game.ruleset with a new game.rules object

• Do we need this at all? Do games just have a top-level version key for the Game engine version?
  • That seems like it might fit better with the "Maps are the future idea"
    • I kinda like moving to maps for everything, mostly cause I never was able fully internalize the difference between rules and maps currently.
      • Maps can and do control things that feel like game mechanics/rules. So I think collapsing down to a single 'concept' here might make more sense
      • The Rules vs Maps handling is the one thing from this doc I feel the least confident about
• Maybe out of bounds handling should be specified here too, since it's relevant to all games (eliminated vs. wrapped etc.)
  • Agreed. I think wrapped is becoming/became a rules mechanic NOT a map mechanic, so makes sense here
    • I wrote this before reading the "Maps are the future" sentence, so I feel this could go either way...

4. Convert game.map from a string to an object

General thoughts about rules vs maps is above

• Is map.author actually useful here?
  • Umm feels easy to include so I would 🤷
  • I don't think its necessary especially if there is a docs page or something with the mappings, but it is fun information and seems easy to send
• Any value in adding a map.name?
  • 🤷
  • If there is a docs page with mappings/a table not a big deal. But again seems easy to include
  • Alternatively, I don't think it would be crazy to remove either name or id as a concept and collapse to whichever (likely id)
    • If we think there is value in having a name that is different than the id it probably makes sense to send it to the snake

Do these changes warrant a new API version?

Yes

I'm a big fan of Semver, and would love at least a semver inspired version here.

So if this isn't be a breaking change to 2.0 maybe this is a 1.1 release or something?

with the one exception of game.map becoming an object instead of a string. Does this warrant a full version bump?

Oh ya this feels like a breaking change... If we can come up with a 'renamed' key, I feel like doing a 1.1 might be fair.
But changing from key to object does feel like it warrants a bump to me

If so, this would be the first major bump we've done during active play. How do we handle API version "1"?

This would obv be more work... But do we want some kinda of 'grace-period' where snakes can opt into the new or older 'schema's?
Like does the snake info return a 'api_version' that opts into 1.x or 2.x?

If we do something like that do we maybe want to ship a 1.1 that's all the additions and then the only diff between 1.1 and 2.0 is the maps object changes? And dropping ruleset?

Other Thoughts

Put new map object under rules

That would remove the collision on map under game, and make it so its not technically a breaking change to ADD the new keys

Removing the old ones does still feel like a breaking change, but since that's more 'cleanup' we'd at least be able to roll out all the new info without breaking existing snakes.
Then dropping the old stuff can be done over a longer period of time. [Maybe could even brownout by occasionally dropping the old keys as a warning to the change over]

Defined Schema for Map Settings

Do we want maps to specify their settings up front? I think it would make sense for a Map at a specific version so always have the same settings keys, so that devs can parse the bodies nicely

Does that mean that custom maps should specify their schema in some discoverable way?

Should the CLI rules listing feature include the expected schema for each map?

Map "Stacking"

Right now in code (or last I looked has probably been a few months) some/most of the maps were implemented by calling the standard map at some point to handle some 'basic' operations on the map.

Looking at the example provided standard and royale map settings I noticed that royale didn't include the settings from standard like foodSpawnChance and minimumFood but I believe those also apply to this game mode

Would we want to simply include all the keys in 'royale'? Or is it worth it to try and have some way to represent the 'stack' of maps present?
Just including all the keys upfront seems easier_ but the idea of stacked maps does seem interesting

[chillfox]

Copy of my previous comments on Discord and the Gist:

From Discord #general-chat

1. Dynamic ttl and value

If you make ttl optional then the null/missing state could represent there being no timeout, the food/hazard is there indefinitely, alternatively, a negative number like -1 could be used to represent no timeout (this would allow for having a default that's specified per map).
Not including value would require stating a default value somewhere, either elsewhere in the json (like game.map.settings.defaultFoodValue or game.rules.defaults...), or in the docs for each map. I think making it optional with a default somewhere would be good for keeping the size of the json down.

I think objects should be removed when they hit 0. So if a snake receives objects with a ttl of 0 then it knows it won't be there on the next turn.

About renaming value to heal/damage, I don't know... From a neatness/aesthetic perspective, I like it a lot, but when considering DRY it complicates things... Renaming them certainly feels more snaky and less "just another API service".

current food behaviour, could be represented as leaving the value/heal out on each food object while setting a default of 100, either elsewhere in the json (see above point about defautls) or the docs

2. Replace game.ruleset with game.rules

looks good when combined with 3.

3. Make game.map an object

looks good, assuming maps can easily add their own properties to settings.
(maybe add food/hazard damage/ttl defaults)

4. new API version

Yes, the changes to ruleset/map will likely break a lot of snakes, so it would be nice to provide people with a small notice period before making it live. I don't think there's any need to support both versions simultaneously, just give people advance notice to get their snakes updated and ready for when it's changed.

---

From the Gist

• I guess I think eating BEFORE food is removed seems like it ideally should eat it. Kinda how eating a food in hazard keeps you alive
• But on the other hand, it feels like maybe a hazard SHOULDN'T damage you on the same turn its removed... Is that inconsistency weird?

It's only inconsistent when you look at it divorced from the greater context. Once you take the context into account it's consistent, you "lean" in favor of the snake. Having both be on the same side of a snake move would lead to the inconsistency of one being in favor of the snake and the other against it.

Is value the best name here? What about Food.heal and/or Hazard.damage?

heal/damage is more fun than value (and better communicates what it is)

These values would be immutable for the lifetime of the object.

Feels like that should be up to the map.

How do we codify the current behavior of "food heals to full"?

game.map.settings.maxHealth, then if maxHealth is 100 and food.heal is 100 you know it heals to max.
This would also be a way of doing a "Time is Life" mode with food providing a small bit of extra time.

About the entire rules vs maps thing.

I feel like there is room for both as they can play different roles.

• Rules should be for tried and tested concepts that we wish to use across several maps, like standard/wrapped, so broadly applicable, they are basically modifiers.
• Maps are for mechanics that are not broadly applicable, or new/experimental.

So the way I see it a new mechanic can start out in a map and if it's a lot of fun and people want to use it across many maps then it should be elevated to a rule at that point.

I think the benefit of having rules and maps is that it allows for a lot of combinations without cluttering the UI up with "mab X, but with Y mechanic" type of maps.

Defined Schema for Map Settings

As long as it's in the docs and the docs are in sync with the deployed engine then that's good enough. But it would be nice having the CLI show it as well.

Map "Stacking"

I kinda like this idea and it would be a more flexible way of doing rules (at least for map makers, but I am getting ideas for stacking a "base" map with a hazard map in the UI here... maybe even multiple, like maps that just implement a single mechanic). I think there's a lot of potential with stackable maps.