Defold Teal Annotations

The Defoldmine
#1

I’ve done some work to generate teal annotations for Defold - been using them for about 2 weeks and they seem to be pretty good.

You can find them at https://github.com/mikatuo/defold-lsp-annotations.

Let me know if you have any questions or suggested changes. I’ll look to make a starter project over the next week or so which would go further into setting up an environment in VS Code and showing example usage.

8 Likes
VS Code - Defold Buddy (extension with productivity tools)
#2

This is cool. Thank you for sharing! How did you generate the annotations? By hand or using a script of some kind?

2 Likes
#3

Thanks! It’s generated via C# code, there is a bit of hacky and hardcoded patches in there, the bulk of the code is in:
https://github.com/mikatuo/defold-lsp-annotations/…/GenerateTealAnnotations.cs
https://github.com/mikatuo/defold-lsp-annotations/…/FunctionTealAnnotator.cs

I think overall the final output is quite usable, although updating Defolds API reference could help with some things. I’m tempted to submit PRs for updating the Defold API reference, if I was to do that where is the repository/files that have the API reference definition?

#4

Thanks. We have a task in our backlog to generate these annotations or extern files as part of the rest of the API reference process or as a stand alone thing:

The API documentation is generated from annotations directly in the engine source code, like this:

When the source code is built we also have a job which extracts the API annotations into files which are later converted to json and sdoc.

What kind of changes did you have in mind?

#5

Ah cool thanks for the information! I think these are the “easy”, uncontroversial fixes:

Area Issue/Fix
b2d.body uses the type vmath.vector3, everywhere else is just vector3, change to vector3
quaternion vs quat inconsistent naming, e.g. vmath.quat returns a quaternion, vmath.normalize takes a quat, change this to quaternion everywhere
go.animate + gui.animate easing parameter takes a vector, is this a vector3 or vector4 or both? Update to correct type(s), I understood this wrong, no change needed here
camera + render uses the type vmath.matrix4, everywhere else is just matrix4, change to matrix4
tilemap.set_tile parameter transform-bitmask is not a valid name for a variable, rename to transform_bitmask

Some other, maybe controversial suggestions:

Area Issue/Fix
timer.delay parameter name repeat is a reserved word which breaks Teal, rename to loop or other relevant name
vmath functions split out quaternion, vector3 and vector4 into separate function definitions, e.g. vmath.lerp, vmath.normalize both would be nicer if it had separate definitions so the input and output types are correctly checked and inferred - my Teal definitions have this change via beautiful hacky code in FunctionTealAnnotator.FunctionDefinitionSplitter
hash the global hash function and the hash type clashes and breaks Teal, in my Teal definitions I renamed the type to hashed, unsure if further Teal versions would fix this without needing changes
1 Like
#6

I believe this function accepts a vector of arbitrary length. Here the docs show using a curve with a vector of length 6 and another vector of length 64.

1 Like
#7

Ah I see, that one is fine as it is then, thanks!

#8

Good suggestions! We will happily accept a PR for these changes.

Ah, yes, that was a poor choice of name. I’m not sure about loop as a name though. Loop makes more sense when some kind of sequence is involved, such as a tween from one value to another or a flipbook animation. Perhaps repeating is better?

Hmm, I’m not sure I fully understand what you need. Take vmath.normalize() as an example. Do you need multiple entries in the API definition, one for vector3 and one for vector4?

Ok, you mean that this could be solved by an update to Teal? I do see the problem with having a function and a type with the same name…

#9

Awesome! I will look to make a PR for those.

Yes that sounds good, much better than loop, why couldn’t I think of that haha!

Yes multiple entries, at the moment this is what happens:

function normalize(v1: vector3|vector4|quaternion): vector3|vector4|quaternion

local n = normalize(vmath.vector3(1.0))
-- typeof n = vector3|vector4|quaternion

Whereas it works nicer if there is multiple entries

function normalize(v1: vector3): vector3
function normalize(v1: vector4): vector4
function normalize(v1: quaternion): quaternion

local n = normalize(vmath.vector3(1.0))
-- typeof n = vector3

It could be solved with an update to Teal - some languages/compilers split types and variables into separate namespaces internally so they can be named the same and don’t clash. On second thought it’s probably long shot for Teal to solve that, and it’s probably better to consider renaming the result type to avoid any potential clashes.

#10

We could submit it as a feature request to Teal? We are in touch with the author of Teal. Perhaps you could submit a feature request to the Teal repo?

#11

repeating or recurring

2 Likes
#12

Thanks, @logan!

With existing extensions for VS Code it would be easy to automate Teal setup for a Defold project/game. In example in Defold Buddy it could work as described here, or in Defold Kit probably similarly.

I think long term it would help to find/make a Lua → Teal annotations converter. Having Teal intellisense for Defold API is a tip of the iceberg. A lot of functionality comes from assets/plugins. The most popular assets have great Lua annotations (i.e. Druid) but it would be a lot of manual work to get Teal on par with Lua. On the other hand if there was a Lua → Teal converter it would be a “Do Once, Cry Once” thing :smiley:

2 Likes
#13

I’ve created a PR to do the updates to documentation:
https://github.com/defold/defold/pull/9420

A Lua to Teal annotations is a good idea, I’m thinking if it was written in TypeScript or JavaScript then it could be included and run within the VS Code extensions. For the moment I’ll leave this as an idea though, too many other things to work on :sweat_smile:

#14

Thanks! I’ve approved it!

2 Likes