[Showcase] Writing resources on TypeScript

[Toliak]

MTASA Typescript

I am developing utility packages for transpiling TypeScript into an MTASA-compatible Lua code. I would like to share that project to receive some suggestions and, I believe, to help someone in resource writing.

Why Lua is not so good

Classes. Lua does not support classes (syntax) from scratch. If you want to write OOP code with your own classes, you have to use metatables to implement class objects behavior.

That's make the source code more complicated, than it could be.

Hints (from your IDE). Lua is dynamic typed language, therefore, it's hard to determine, what the variable is and, hence, IDE cannot hint you function declarations, object methods and etc.

MTASA Lua is still 5.1 (it is not developing). Lua, like any programming language, is developing, however MTASA core strongly linked to Lua 5.1.

Why TypeScript

There is TypeScriptToLua project. My project is based on TypeScriptToLua (I use it as a dependency). General purpose of TypeScriptToLua: convert (transpile) typescript code into Lua code. Thus, you can use TypeScript without modifying MTASA core.

You are available to not use types in some parts of code (you are not restricted to use types everywhere).

The TypeScript is being developed by Microsoft and, I believe, that TypeScript will be alive for several years.

When to not use TypeScript (where to use Lua instead of TypeScript)

1. If you are not familiar with Lua or with scripting in general.

2. if you are writing simple script.

Introduction Video

I have made the video, where I describe Lua disadvantages, explain, why I have chosen TypeScript (and language transpiling) and write an example.

 

Few word about mtasa-lua-types

I have created this package to provide MTASA declarations in TypeScript. If you would like to create a resource, you haven't to install it manually, just use the boilerplate.

Quick Start

I have provided the tutorial here: https://github.com/mtasa-typescript/resource-boilerplate.

So, you have to install NodeJS and download my boilerplate. And,... you are ready to code.

If you have any ideas, issues or suggestions -- post them below, or in youtube comments, or in github issues

Example code (from youtube video)

import { Player } from 'mtasa-lua-types/types/mtasa/server/oop/Player';
import { mtasa } from 'mtasa-lua-types/types/mtasa/server';

interface GithubCommitApiResponse {
    commit: {
        message: string;
    }
}
 
mtasa.addCommandHandler('getcommit', function(player: Player, cmd: string) {
    mtasa.fetchRemote(
        'https://api.github.com/repos/mtasa-typescript/mtasa-lua-types/commits?per_page=1',
        (data: string) => {
            const json = mtasa.fromJSON(data) as GithubCommitApiResponse
            mtasa.outputConsole(`The last commit message: ${json.commit.message}`)
        }
    )
})

Future plans

- Github bot, that will crawl mtasa wiki and update mtasa-lua-types continuously

- Add better hinting for `addEventHandler` function

Links

WebSite: https://mtasa-typescript.github.io/

GitHub MTASA TypeScript Projects: https://github.com/mtasa-typescript

Resource Boilerplate: https://github.com/mtasa-typescript/resource-boilerplate

Resource Example: https://github.com/mtasa-typescript/resource-example

[Toliak]

Event Types Hinting

I have implemented the types for events.

Example code is available on GitHub

Demonstration

How To Use

Event Handlers

mtasa.addEventHandler<mtasa.Event./* specify the event type */>(
    /* the event name will be hinted automatically */,
    /* put the source element here*/,
    function (/* function arguments will be hinted */) {
        // Insert the payload
    },
);

Events trigger (with custom event, for example)

export interface YourCustomEvent extends GenericEventHandler {
    name: 'MyCustomEventName'; // You can specify `const enum` for multiple names
    function: (this: void, ...args: any[]) => void;
}

mtasa.triggerClientEvent<YourCustomEvent>(
    /* put the source player (or root) */,
    /* the event name will be hinted automatically */,
    /* put the source element here*/,
    /* function arguments will be hinted */
);

---

What are you thinking about the idea? 
Is that interesting for you (and why, if not)?

[Toliak]

I have released the 1.0 version of MTASA TypeScript project.

Main changes

- Upgraded the Wiki parser, OOP definitions and add generics (for event declarations or key binding)

- YML format for meta file (with schema, so you will receive hints while filling it). Supports multiple resources in the same boilerplate.

- Reduced steps to create a new project

- Better linting for declared in meta files and client-, server- side import

Quick Start

1. Steps to create a new project

a) Install NodeJS from the official web site.

b) Open a console in the resources directory and enter 

npx mtasa-lua-utils new-project

Fill the inputs and select the feature you would like to use. That's all, you are ready to code

 

2. Available commands

Since, there is a multiple resources support, you can use the command to create a new one:

npx mtasa-lua-utils new-resource

To build the entire project use one of the listed commands:

npx mtasa-lua-utils build
npm run build

 

3. YML format for the meta file

info:
    name: TypeScriptResource     # Name of the resource
    type: script                 # Resource type

compilerConfig:
    srcDir: TypeScriptResource   # src/TypeScriptResource will be the script root folder

scripts:                         # Declarations of all TS files, used in the resource
    - src: client.ts
      type: client
      cache: false

    - src: server.ts
      type: server
      cache: false

    - src: utils.ts
      type: shared
      cache: false
      
---

# Here you can put another resource declaration

 

Schema for the YML file already prepared in the boilerplate for VSCode and WebStorm. Schema file location, if you would like to specify it manually.

[The_GTA]

Nice work! I am interested in the debug-ability of TypeScript code. Last time I used TypeScript in connection with JavaScript I saw that you could annotate function signatures with types or leave out the types. By leaving out the types you did revert back to regular Lua with all of its glory (and pain?).

Anyway, since we are using Lua it is going to be the backend of your solution. What if we introduce errors into the script? In a traditional Lua resource we do receive warning and error messages into the scripting debug console (both server and client) with line numbers and a somewhat-helpful message. How do they look like in your solution? Is it a mess due to the transpilation? Or have you compiled to bytecode directly as well as written a custom debug-info generator to adjust for the TypeScript-based line numbers? Have you introduced any kind of new debug messages to help developers?

I am asking this because what if somebody is using your solution and then comes asking inside of our forum Scripting section. We have to know how to support your TypeScript-based resources!

Edited September 14, 2021 by The_GTA

[Toliak]

On 14/09/2021 at 21:54, The_GTA said:

Nice work! I am interested in the debug-ability of TypeScript code. Last time I used TypeScript in connection with JavaScript I saw that you could annotate function signatures with types or leave out the types. By leaving out the types you did revert back to regular Lua with all of its glory (and pain?).

Thank you for reply! Sorry for a long response.

 

On 14/09/2021 at 21:54, The_GTA said:

Anyway, since we are using Lua it is going to be the backend of your solution. What if we introduce errors into the script? In a traditional Lua resource we do receive warning and error messages into the scripting debug console (both server and client) with line numbers and a somewhat-helpful message.

 Yes. The output messages will have the filename and line number of the error (in generated Lua file).

On 14/09/2021 at 21:54, The_GTA said:

How do they look like in your solution? Is it a mess due to the transpilation? Or have you compiled to bytecode directly as well as written a custom debug-info generator to adjust for the TypeScript-based line numbers? Have you introduced any kind of new debug messages to help developers?

Yes. The original line numbers and file names will be lost, if error happens in runtime. However, there are several solutions to debug the code:

1. (Hard) Look at lua context (function names, class names, variable names). The TypeScriptToLua (TSTL) library I'm using does not obfuscate or minimize the code, therefore, result Lua code is read-able. The user can match the Lua code and TS code and determine the error line.

2. (Simple) Lua itself provides debug.traceback function. TSTL wraps the function into its own and in runtime debug.traceback can be used in code to show the current full traceback log.

If the user will combine p.1 and p.2, he will be able to debug his script in less painful way

If you have some ideas, how can I improve the logs, you can write them here or in the issues.

[The_GTA]

10 minutes ago, Toliak said:

Thank you for reply! Sorry for a long response.

You're welcome! Don't worry, I am a patient man.

10 minutes ago, Toliak said:

Yes. The original line numbers and file names will be lost, if error happens in runtime. However, there are several solutions to debug the code:

1. (Hard) Look at lua context (function names, class names, variable names). The TypeScriptToLua (TSTL) library I'm using does not obfuscate or minimize the code, therefore, result Lua code is read-able. The user can match the Lua code and TS code and determine the error line.

2. (Simple) Lua itself provides debug.traceback function. TSTL wraps the function into its own and in runtime debug.traceback can be used in code to show the current full traceback log.

If the user will combine p.1 and p.2, he will be able to debug his script in less painful way

So my hunch about the transpilation debug message adjustment was correct. I think that the users of your library have to be made aware that in support cases they have to show us both the transpiled as well as the input code for proper support.

I like that you want to keep the transpilation output human-friendly. I think it is a very important strategy to the success of your product. Being able to understand how the code was generated from the original source will aid developers in the trust into your code generator. It will also raise the confidence that your product performs well. Good choice!

You seem to go beyond my expectations in overriding default Lua debug facilities. While this is an interesting concept I am afraid not many people make use of these. There should be more tutorials on MTA forums about proper debugging of code and you should contribute to those with how your product is really well made regarding debugability!

Edited October 24, 2021 by The_GTA