How do you use LuaCATS type annotations in Defold's built-in script editor?

Questions
1

Hello,

I’ve noticed that type annotations (such as ---@param and ---@return) work correctly in Defold’s built-in script editor, but I haven’t been able to find any official Defold documentation that explicitly discusses them.

My question is: is there an official guide or set of best practices for using these annotations in the Defold editor, or should I rely solely on external LuaCATS documentation?

Are there any known limitations or specific behaviors to keep in mind when using annotations in the built-in editor?

A search of the forum turned up only this thread mentioning the topic.

Thanks in advance for any clarification!

2

I didnt find any more ressources for this either, but here is how I am using it:

  • yes you can rely on the luaCAT documentation for annotation doc, because Defold use the luaLS server as LSP so it is this one.
  • I use the Defoldkit VSCode plugin while in VSCode, this pulls in all Defold API annotations into the project so you have great autocomplete and checks in Vscode, but I think also then in the Defold editor. In VSCode just configure that .script and .gui_script and .editor_script are lua language.
  • I think that in the Defold bets 1.13.2 there is improvements on the Lua tooltips inside Defold editor.. so it would feel a lot more like in VS Code.

When I am working in a .script or lua module, I personnally put at the start of my file the class Definition of my “self” instance.
For example in player.script:


---@class PlayerData
---@field sprite url 
---@field velocitiy vector3

---@param context PlayerData
local function reset_state(context)
  context.velocity.x =0
  context.velocity.y = 0
end

---@param self PlayerData 
function init(self)
   self.sprite = msg.url('#sprite')
   self.velocity = vmath.vector3()
end

---@param self PlayerData
---@param dt number
function late_update(self, dt)
   reset_state(self)
end

(This example is lame)
So like this, everytime I add or need a new state variable, I have an error in checks if I dont add it to the script class, and I have full autocomplete in my code.

But the Defold Editor is still a bit hacky about this. VSCode has a much much better autocomplete and sugestion features.

3

I would add that working like this enforce you to think a bit more before writing code like
“Ok… I need a speed for this, I need the sprite url for that, I need a timer duration this, a boolean switch for this state etc…”

This made me invaluably more efficient at writing good code at first shot.

4

Thanks a lot for the detailed reply and for sharing your workflow, @Mathias. It’s exactly the kind of practical information I was looking for.

Building on your idea, I initially had trouble with vmath.vector3 parameters—using table as the type—but I’ve now resolved it by doing this:

---@class vector3
---@field x number
---@field y number
---@field z number

Regarding keeping an eye out for the next version of Defold (1.13.2), are you referring to this pull request?

If I understand correctly, with this change there will no longer be a need to manually define this data type, right?

5

Yes that’s right, they include the annotations for bultin type inside the editor. I think all of this is based on the work of the Defoldkit VSCode extension. This extension has a setup command that pulls in all builtin annotations inside your project so you dont have to write them. I think they have integrated these inside the core code.

1 Like