Hard Light Productions Forums

FreeSpace Releases => Scripting Releases => Topic started by: m!m on June 22, 2020, 12:03:50 pm

Title: Generate Type definitions for FSO API
Post by: m!m on June 22, 2020, 12:03:50 pm
Over the past few months I have been working on improving the quality of the documentation FSO automatically generates for the scripting API. The most important basic feature of that was to add a JSON generator in addition to the existing HTML one for the documentation. This allows to write external tools that take this information and do something useful with it. My use case was to generate type definitions for both Lua and TypeScript.

I wrote a small tool that takes the JSON generated by FSO and writes another file that can be used for getting much better coding assistance when writing scripts for FSO.
This tool is written in TypeScript and is published on npm: https://www.npmjs.com/package/fso-ts-generator
If you install that globally you will get a fso-typings command line tool. The built-in help messages should hopefully be sufficient...

The Lua generator was written specifically for this IntelliJ plugin which I find very useful for writing scripts for FSO: https://plugins.jetbrains.com/plugin/9768-emmylua
If you use the typings generator then simply make it generate the type information to "data/api/fso.lua" and the plugin will pick up the definitions and offer you code completion for most API functions.

Wait, why TypeScript?
Because of this: https://github.com/TypeScriptToLua/TypeScriptToLua
That is a compiler that translates TypeScript to Lua which was the original reason I built the JSON support but never got around to actually using it "in production".

That is all,
Have a nice day :p
Title: Re: Generate Type definitions for FSO API
Post by: wookieejedi on June 22, 2020, 01:07:09 pm
Awesome, thanks for the formal writeup and info. This tool is highly useful.
Title: Re: Generate Type definitions for FSO API
Post by: jadeddragoon on September 17, 2021, 09:44:11 pm
Note, if you get something like:

│[email protected] ~ $ fso-typings generate -j scripting.json -o fsoluaapi.ts
│Generating TypeScript definitions for scripting.json ... TypeError: Cannot read property 'readFile' of undefined

It means your Node.js version is too old. Tested working with Node.js 14.17.6