Can't figure out the best way to annotate game code (example inside!)

[alexbalandi]

I'm new to Lua, essentially trying to help my friend right now with their game project. It has existing code, I wish to add some type annotations to it so that it's easier to understand what's going on and have nice IDE tooltips, I'm using vscode plugin right now.

So, here's my simple case, I have table:

actions.all = {
  "retreat",
  "move",
  "swap",
  "forcedMove",
  "melee",
  "shoot",
  "shoot2",
  "breakthrough",
  "enclosing",
  "supportAttack",
  "supportDefence",
  "supportBoth",
  "supportAttackPike",
  "supportDefencePike",
  "stanceShieldwall",
  "stanceLastman",
  "stanceBarrage",
  "encamp",
  "uncamp",
  "destroyCamp",
  "buildFort",
  "demountFort",
  "destroyFort",
  "rest",
  "respire",
}

Now first of all simply using enum on it won't give me nice typehints (I even made an issue here : #2435)
but I found a way to get around it like this:

---@enum (key) ActionName
local enumed_action_names = {
  retreat = 1,
  move = 2,
  swap = 3,
  forcedMove = 4,
  melee = 5,
  shoot = 6,
  shoot2 = 7,
  breakthrough = 8,
  enclosing = 9,
  supportAttack = 10,
  supportDefence = 11,
  supportBoth = 12,
  supportAttackPike = 13,
  supportDefencePike = 14,
  stanceShieldwall = 15,
  stanceLastman = 16,
  stanceBarrage = 17,
  encamp = 18,
  uncamp = 19,
  destroyCamp = 20,
  buildFort = 21,
  demountFort = 22,
  destroyFort = 23,
  rest = 24,
  respire = 25,
}

---@type ActionName[]
actions.all = {}

---@param actionName ActionName
for actionName, _ in pairs(enumed_action_names) do
  table.insert(actions.all, actionName)
end

I can now nicely use ActionName as parameter in functions, but I get warnings and otherwise not-very-useful typehints when doing sth like this:

---@type table<ActionName, ActionName[]>
local forbids = {}
forbids.retreat = { "retreat" }
forbids.move = { "rest", "breakthrough" }

It says: Fields cannot be injected into the reference of `table<ActionName, ActionName[]>` for `swap`. To allow injection, add `[any]: any` to the definition.Lua Diagnostics.(inject-field)

I'm probably not the first who tries to do sth like this, would appreciate any pointers / thoughts / links to guides! My background is mostly python (if that matters).

[alexbalandi]

One other thing that bugs me, consider this:

actions.isSupport = {
  supportAttack = true,
  supportDefence = true,
  supportBoth = true,
  supportAttackPike = true,
  supportDefencePike = true,
}
---@param action ActionName
---@return boolean
function actions.IsSupport(action)
  return actions.isSupport[action]
end

When hovering over actions.isSupport I get a nice typehint:

(field) actions.isSupport: {
    supportAttack: boolean = true,
    supportAttackPike: boolean = true,
    supportBoth: boolean = true,
    supportDefence: boolean = true,
    supportDefencePike: boolean = true,
}

Now when I annotate the table

---@type table<ActionName, boolean>
actions.isSupport = {
  supportAttack = true,
  supportDefence = true,
  supportBoth = true,
  supportAttackPike = true,
  supportDefencePike = true,
}

I get less verbose typehints:
(field) actions.isSupport: table<ActionName, boolean>

Can I annotate it and make sure it's still verbose when hovering?

[carsakiller]

Unfortunately not. A table is either defined as a certain type so that it can be expanded and retains type safety, or is defined as being "static" with no annotated type. If the intention is to never change the table, we can gladly show the known possible values. But if you specify the type, the assumption is that the table will then be mutated, so we cannot be sure that the types defined initially will still be there.

At least this is how I have understood it and worked with it.

[alexbalandi]

Tbh, you're absolutely correct here - after refactoring the code a bit more I've found that yes, if I want "fixed in stone" fields in table, I can just explicitly define it like ---@field headquarters? { var: string, side: integer }, otherwise it is actually better to have these less verbose notations.

[alexbalandi]

It seems the better way to go about this is using class:

---@class ActionTable
---@field [ActionName] ActionName[]

---@class ActionTable
local forbids = {}

This ends up giving me this kind of type hints:

(field) ActionTable.move: ActionName[] {
    [1]: ActionName,
    [2]: ActionName,
}

Which is ALMOST what I want, now I just need to find a way to make sure actual value also gets displayed along the ActionName

[carsakiller]

I don't think I would recommend this. Chances are that it would be better to use an enum and reconsider how you are storing the action names. Classes are used pretty much always for tables with string keys.

Without an example of how you are using/consuming the action names, I can't definitively say this is not the best way to do it, though.

[carsakiller]

I added a longer explanation on your issue, but here is some (untested) example code more tuned to your use:

local actions = {}

---@enum actions.all
actions.all = {
    retreat = 1,
    move = 2,
    swap = 3,
    forcedMove = 4
}

---If you need the names of actions, you can index this
actions.names = {
    "retreat",
    "move",
    "swap",
    "forcedMove"
}

---Get the name of an action
---@param action actions.all
function actions.getName(action)
    return actions.names[action]
end

local character = {}

---@param action actions.all
function character:setAction(action)
    self.action = action
end

function character:getAction()
    return self.action
end

---Example usage

character:setAction(actions.all.retreat)

local characterAction = character:getAction()
local characterActionName = actions.getName(characterAction)

-- "Character is performing action: retreat"
print("Character is performing action: " .. characterActionName)

[alexbalandi]

Well, this looks neat, but most of the already written code does stuff like this:

---@param unit Unit
---@param action ActionName
function units.ToggleActivation(unit, action)
  if unit.active[action] then unit.active[action] = nil else unit.active[action] = true end
end

and a few places where ipairs(actions.all) is used for iteration.

So I mostly just need an alias for action names that is defined from table AND when I expand on the code with stuff for ai (which is why I'm doing the whole annotating/refactoring thing ...) - I might want to iterate over all actions / sort them / etc.

Also answered you in the issue, you're certainly right about many things.

Thank you very much for your detailed responses, really appreciate it! Extra thanks for pointing out the : and self. syntax sugar, didn't know it exists in lua!