THIS IS UNFINISHED AND UNPUBLISHED. READ AT YOUR OWN RISK.

reflect

A software article by Efron Licht July 2023

Our goals

Arbitrary manipulation of gamestate at runtime with a forgiving API. Ideally, the combination of console and other debug tools should mean there’s no difference between ‘playing’ the game and ‘building/debugging’ the game.

High-level goals:

• modify arbitray gamestate at runtime
  • change variables
  • call functions, both built-in to the console or available by walking the gamestate DAG
• UI is also gamestate
  • modify UI live
  • connect variables to player input (mouse position, keyboard input, etc) Maybe it’s easiest if I demonstrate.

performance

‘idle’ performance should be as close to zero as possible. The console should not affect performance unless it is being used.

the console should start up instantly and not affect the game’s startup time: hard max of 5ms. doing a eager-nonblocking load and not letting the console open on the first frame is totally fine.

Commands should be reasonably performant.

• What does ‘reasonably performant’ mean in the context of a console?

OTOH, any ‘callback’ behavior that triggers on gamestate changes should be as fast as possible, since it can be triggered arbitrarily often. it is OK for debugging tools to update less often than the game does: the console should NEVER drop a frame except immediately after processing a new command.

example uses of the console

modify UI live

‘cheat codes’:

• player.hp = 1000000

  change gun defintions live for NPCs and players

enable or disable UI elements

• toggle ui.healthbar

connect variables to player input (mouse position, keyboard input, etc)

• followmouse ui.healthbar
• followmouse player

console UI

traditional console UI: command history, autocomplete, etc. history is saved to disk.

/* ALIAS Op = iota // alias a key to another key CALL // call a function ENV // print environment variables CPIN // Pin a value to a constant literal RPIN // Pin a value to reference another key. if self-referential, it will ‘freeze’ the value. // TODO: OPIN? pin with operator, like “pin player.X npc[0].X + 20” TOGGLE // toggle a boolean value FOLLOWMOUSE // set a value to follow the mouse position until followmouse is called again FLATWATCH // watch all the values within a struct or field for changes HELP // print help LIST // list possible operations LOAD // load a value from a file. only ‘.json’ for now. MOD // modify a value using an operator PRINT // print a value SAVE // save a value to a file. only ‘.json’ for now. CONCATLOAD // load a value from a file and concatenate it with the current valueg DESTROY // destroy NPCS, WALLS, PROJECTILES, PICKUPS, or ALL of them RESTART // restart the game SET // set a value SETMOUSE // set a value to the mouse position UNALIAS // unbind all aliases UNWATCH // stop watching all values UNPIN // unpin one or more values WATCH // watch a value for changes OP_N // number of operations: must be last */

console commands

forgiving API

• console should never break the game entirely: all changes should be caught by reset at very least
• panics are caught and logged: console should never crash the game
• no worrying about capitalization: unexported fields should be invisible
  • warn on name conflicts at runtime
• autocomplete should suggest fields and methods
• easy access to array and slice fields
  • combine LUA-like and Python-like index syntax:
  • npcs.0 <==> npcs[0]
  • npcs.-1 <==> npcs[len(npcs)-1]
  • can go back and forth between struct-like, map-like, and array-like access: suppose npcs = []struct{foo map[string]int}: npcs.0.foo.bar <==>npcs[0].foo[“bar”]`
  • user should not have to consider pointer vs value, slice vs array
  • automatic type coersions
    • numbers: use c-like rules, casting to the widest type to do math and then truncating back to the original type. numerical error, etc, is OK: this is meant for debugging, not truth.
    • cast strings to and from other types as needed: other types can be ad-hoc made from strings via TextUnmarshaler
• prefer toggle ui.healthbar over ui.healthbar.enabled = !ui.healthbar.enabled
• prefer followmouse ui.healthbar over follow(ui.healthbar, mouse)
• automatically handle pointer ref/deref where possible: console should have no idea what a pointer is: everything should be OK for reflect.Value.CanAddr().

implementing the console

building autocomplete

CLIs without autocomplete are a pain to use. Autocomplete not only saves on typing, it helps a user discover what commands are available.

We’d like to have a variety of autocompletes available depending on what kind of operation the player is attempting.

For example, for the FIRST word in a prompt, we might want to suggest operations and fields, since all of the following are valid operations:

tog

player.x *= 2 # first word is a field, for a 'modify-in-place' operation

We also might want to suggest known savefiles for the load and save operations, like this:

// completions is a struct that holds all the possible completions for a given prompt.
// see suggestedCompletion for how it's used.
type completions struct {
  ops    []string // operations: toggle, mod, set, etc. only valid for the first word in a prompt.
  fields []string // fields and methods: player.x, ui.healthbar.enabled, etc. valid for any word in a prompt.
  // augment-assignment operators:  +=, -=, *=, /=, =, &=, |=, ^=, %=, <<=, >>=, &^=
  assignops []string 

  saveFiles []string // valid for the third word in a prompt, during 'save' or 'load'  

  // aliases is a map from alias to the aliased value.
  aliases map[string]string 
}

func suggestCompletion(c *completions, line string, cursor int) string {
		if cursor < len(line) {
      return "" // cursor is in the middle of a line: no suggestions
		} 
  
    // what word are we completing?
    i := strings.IndexAny(line, " \t\n") // position of first whitespace, if any
    for i+1 < len(line) && (line[i+1] == ' ' || line[i+1] == '\t') {
      i++ // skip whitespace
    }
    j := strings.LastIndexAny(line, " \t\n\r") // position of last whitespace, if any

    switch {
    case i == -1: // first word: choose an op or field. ops take priority.
      if completion := autocomplete(c.completions.ops, line); completion != "" {
        return completion
      }

    case i == j: // second word.
        firstWord, rem := line[:i], line[i:]

        // was the first word an alias?
        if alias, ok := c.aliases[firstWord]; ok {
           firstWord = alias // yes: replace it with the alias
        }

        // is the first word an op?
        if k := sort.SearchStrings(c.completions.ops, firstWord); k >= 0 && k < len(c.completions.ops) && c.completions.ops[k] == firstWord {
          // yes: autocomplete the rest of the line as a field. e.g, "toggle ui.healthbar"
          return line[:i+1] + autocomplete(c.completions.fields, strings.TrimSpace(rem))
        }

        // was the first word a field?
        if k := sort.SearchStrings(c.completions.fields, firstWord); k >= 0 && k < len(c.completions.fields) && c.completions.fields[k] == firstWord {
          // yes: allow autocomplete for augment-assignment operators. e.g, "player.x += player.y"
          return line[:i+1] + autocomplete(c.completions.assignops, strings.TrimSpace(rem))
        }

        // we don't know: allow autocomplete for fields anyways.
        return line[:i+1] + autocomplete(c.completions.fields, strings.TrimSpace(rem))
    case strings.Contains(line, "save"),  strings.Contains(line, "load"): 
      // third word during 'save' or 'load': choose a file
        return line[:j+1] + autocomplete(c.saveFiles, line[j+1:])
    default: // third word, not during 'save' or 'load': choose a field, like for 'player.x += player.y'
        return line[:j+1] + autocomplete(c.completions.fields, line[j+1:])
    }
}