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

**URL:** <https://forum.defold.com/t/how-do-you-use-luacats-type-annotations-in-defolds-built-in-script-editor/83249>\
**Category:** Questions\
**Created:** [September 19, 2026, 6:36am UTC](https://forum.defold.com/t/how-do-you-use-luacats-type-annotations-in-defolds-built-in-script-editor/83249 "2026-09-19T06:36:29Z")\
**Posts on this page:** 7\
**Page:** 1

<div class="post-metadata">

**Author:** ![feebleflame](https://forum-defold.b-cdn.net/user_avatar/forum.defold.com/feebleflame/32/43780_2.png) [@feebleflame](https://forum.defold.com/u/feebleflame)\
**Post date:** [September 19, 2026, 6:36am UTC](https://forum.defold.com/t/how-do-you-use-luacats-type-annotations-in-defolds-built-in-script-editor/83249/1 "2026-09-19T06:36:29Z")

</div>

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](https://defold.com/manuals/writing-code/#writing-lua-code) 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](https://luals.github.io/wiki/annotations/)?

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](https://forum.defold.com/t/why-do-you-personally-prefer-defold-over-unity-for-2d-games/82087/6)mentioning the topic.

Thanks in advance for any clarification!

---

<div class="post-metadata">

**Author:** ![Mathias](https://forum-defold.b-cdn.net/user_avatar/forum.defold.com/mathias/32/44015_2.png) [@Mathias](https://forum.defold.com/u/Mathias)\
**Post date:** [September 19, 2026, 7:08am UTC](https://forum.defold.com/t/how-do-you-use-luacats-type-annotations-in-defolds-built-in-script-editor/83249/2 "2026-09-19T07:08:48Z")

</div>

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:

```lua

---@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.

---

<div class="post-metadata">

**Author:** ![Mathias](https://forum-defold.b-cdn.net/user_avatar/forum.defold.com/mathias/32/44015_2.png) [@Mathias](https://forum.defold.com/u/Mathias)\
**Post date:** [September 19, 2026, 7:13am UTC](https://forum.defold.com/t/how-do-you-use-luacats-type-annotations-in-defolds-built-in-script-editor/83249/3 "2026-09-19T07:13:35Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![feebleflame](https://forum-defold.b-cdn.net/user_avatar/forum.defold.com/feebleflame/32/43780_2.png) [@feebleflame](https://forum.defold.com/u/feebleflame)\
**Post date:** [September 19, 2026, 7:49am UTC](https://forum.defold.com/t/how-do-you-use-luacats-type-annotations-in-defolds-built-in-script-editor/83249/4 "2026-09-19T07:49:37Z")

</div>

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:

```lua
---@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](https://github.com/defold/defold/pull/12851)?

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

---

<div class="post-metadata">

**Author:** ![Mathias](https://forum-defold.b-cdn.net/user_avatar/forum.defold.com/mathias/32/44015_2.png) [@Mathias](https://forum.defold.com/u/Mathias)\
**Post date:** [September 19, 2026, 8:28am UTC](https://forum.defold.com/t/how-do-you-use-luacats-type-annotations-in-defolds-built-in-script-editor/83249/5 "2026-09-19T08:28:28Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![britzl](https://forum-defold.b-cdn.net/user_avatar/forum.defold.com/britzl/32/23_2.png) [@britzl](https://forum.defold.com/u/britzl)\
**Post date:** [September 20, 2026, 7:55am UTC](https://forum.defold.com/t/how-do-you-use-luacats-type-annotations-in-defolds-built-in-script-editor/83249/6 "2026-09-20T07:55:23Z")

</div>

The type annotations we support are those of the Lua Language Server:

> **[Annotations](https://github.com/LuaLS/lua-language-server/wiki/Annotations)**
>
> A language server that offers Lua language support - programmed in Lua - LuaLS/lua-language-server

@vlaaad and @AGulev recently did a large push to update the annotations within our codebase so that you get much better support from the code editor.

---

<div class="post-metadata">

**Author:** ![AGulev](https://forum-defold.b-cdn.net/user_avatar/forum.defold.com/agulev/32/4541_2.png) [@AGulev](https://forum.defold.com/u/AGulev)\
**Post date:** [September 20, 2026, 7:57am UTC](https://forum.defold.com/t/how-do-you-use-luacats-type-annotations-in-defolds-built-in-script-editor/83249/7 "2026-09-20T07:57:45Z")

</div>

It’s already available in 1.3.2 beta:

> [@Defold 1.13.2 BETA](https://forum.defold.com/t/defold-1-13-2-beta/83226):
>
> Defold 1.13.2 Disclaimer This is a BETA release, and it might have issues that could potentially be disruptive for you and your team’s workflow. Use with caution. Use of source control for your projects is strongly recommended. Access to the beta Download the editor or bob.jar from GitHub: [Release v1.13.2 - beta · defold/defold · GitHub](https://github.com/defold/defold/releases/tag/1.13.2-beta)Beta notes: This version includes support for Rich Text labels and GUI nodes. The new functionality allows developers to add markup to text in order to change …

> **[Release v1.13.2 - beta · defold/defold](https://github.com/defold/defold/releases/tag/1.13.2-beta)**
>
> Defold version 1.13.2
> Channel=beta sha1: fb9f13b
> date = 2026-09-16 11:05:10