├── .docs
├── install.gif
└── mtasa_meta.gif
├── .eslintrc.yml
├── .github
├── ISSUE_TEMPLATE
│ ├── ----bug-report.md
│ └── ---feature-request.md
├── dependabot.yml
└── workflows
│ └── package.yml
├── .gitignore
├── .idea
├── jsonSchemas.xml
├── prettier.xml
├── watcherTasks.xml
└── workspace.xml
├── .prettierignore
├── .prettierrc.json
├── .vscode
├── extensions.json
├── settings.json
└── tasks.json
├── README.md
├── mtasa-meta.yml
├── package.json
├── src
└── TypeScriptResource
│ ├── client.ts
│ ├── server.ts
│ └── utils.ts
├── tsconfig.json
└── types
└── additional.d.ts
/.docs/install.gif:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/mtasa-typescript/resource-boilerplate/4f8a74474516068fd394837826e029b6db088081/.docs/install.gif
--------------------------------------------------------------------------------
/.docs/mtasa_meta.gif:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/mtasa-typescript/resource-boilerplate/4f8a74474516068fd394837826e029b6db088081/.docs/mtasa_meta.gif
--------------------------------------------------------------------------------
/.eslintrc.yml:
--------------------------------------------------------------------------------
1 | env:
2 | es2021: true
3 | extends:
4 | - 'eslint:recommended'
5 | - 'plugin:@typescript-eslint/recommended'
6 | parser: '@typescript-eslint/parser'
7 | parserOptions:
8 | ecmaVersion: 12
9 | sourceType: module
10 | plugins:
11 | - '@typescript-eslint'
12 | rules: {}
13 |
--------------------------------------------------------------------------------
/.github/ISSUE_TEMPLATE/----bug-report.md:
--------------------------------------------------------------------------------
1 | ---
2 | name: '⚠️ Bug report'
3 | about: Create a report to help us improve
4 | title: '⚠️ Name of the issue'
5 | labels: bug
6 | assignees: ''
7 | ---
8 |
9 | # Describe the bug
10 |
11 | A clear and concise description of what the bug is.
12 |
13 | ## To Reproduce
14 |
15 | Steps to reproduce the behavior:
16 |
17 | 1. Go to '...'
18 | 2. Click on '....'
19 | 3. Scroll down to '....'
20 | 4. See error
21 |
22 | ## Expected behavior
23 |
24 | A clear and concise description of what you expected to happen.
25 |
26 | ## Screenshots
27 |
28 | If applicable, add screenshots to help explain your problem.
29 |
30 | # Desktop information
31 |
32 | Provide you OS version information
33 |
34 | ## NPM Version
35 |
36 |
37 |
38 | ```
39 | Paste result here
40 | ```
41 |
42 | ## NPM Package versions
43 |
44 |
45 |
46 | ```
47 | Paste result here
48 | ```
49 |
50 | # Additional context
51 |
52 | Add any other context about the problem here.
53 |
--------------------------------------------------------------------------------
/.github/ISSUE_TEMPLATE/---feature-request.md:
--------------------------------------------------------------------------------
1 | ---
2 | name: '⭐ Feature request'
3 | about: Suggest an idea for this project
4 | title: '⭐ Name of the issue'
5 | labels: enhancement
6 | assignees: ''
7 | ---
8 |
9 | # Description
10 |
11 | A clear description of the feature
12 |
13 | ## Is your feature request related to a problem? Please describe.
14 |
15 | A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
16 |
17 | # Suggestion
18 |
19 | ## Describe the solution you'd like
20 |
21 | A clear and concise description of what you want to happen.
22 |
23 | ## Describe alternatives you've considered
24 |
25 | A clear and concise description of any alternative solutions or features you've considered.
26 |
27 | # Additional context
28 |
29 | Add any other context or screenshots about the feature request here.
30 |
--------------------------------------------------------------------------------
/.github/dependabot.yml:
--------------------------------------------------------------------------------
1 | version: 2
2 | updates:
3 | # Fetch and update latest `npm` packages
4 | - package-ecosystem: npm
5 | directory: '/'
6 | schedule:
7 | interval: daily
8 | time: '00:00'
9 | open-pull-requests-limit: 10
10 | reviewers:
11 | - toliak
12 | assignees:
13 | - toliak
14 | commit-message:
15 | prefix: fix
16 | prefix-development: chore
17 | include: scope
18 | # Fetch and update latest `github-actions` packages
19 | - package-ecosystem: github-actions
20 | directory: '/'
21 | schedule:
22 | interval: daily
23 | time: '00:00'
24 | open-pull-requests-limit: 10
25 | reviewers:
26 | - toliak
27 | assignees:
28 | - toliak
29 | commit-message:
30 | prefix: fix
31 | prefix-development: chore
32 | include: scope
33 |
--------------------------------------------------------------------------------
/.github/workflows/package.yml:
--------------------------------------------------------------------------------
1 | name: NPM Package
2 |
3 | on:
4 | pull_request:
5 | paths-ignore:
6 | - '**.md'
7 | push:
8 | paths-ignore:
9 | - '**.md'
10 |
11 | jobs:
12 | build:
13 | runs-on: ubuntu-latest
14 | steps:
15 | - uses: actions/checkout@v3
16 | - name: Setup node 14
17 | uses: actions/setup-node@v3.0.0
18 | with:
19 | node-version: 14.x
20 | - name: Cache Node files
21 | uses: actions/cache@v2.1.7
22 | env:
23 | cache-name: cache-node-modules
24 | with:
25 | # npm cache files are stored in `~/.npm` on Linux/macOS
26 | path: |
27 | ~/.npm
28 | key: ${{ runner.os }}-build-${{ env.cache-name }}-${{ hashFiles('**/package-lock.json') }}
29 | restore-keys: |
30 | ${{ runner.os }}-build-${{ env.cache-name }}-
31 | ${{ runner.os }}-build-
32 | ${{ runner.os }}-
33 | - run: npm install
34 | - run: npm run build
35 | prettier:
36 | runs-on: ubuntu-latest
37 | steps:
38 | - uses: actions/checkout@v3
39 | - name: Setup node 14
40 | uses: actions/setup-node@v3.0.0
41 | with:
42 | node-version: 14.x
43 | - name: Cache Node files
44 | uses: actions/cache@v2.1.7
45 | env:
46 | cache-name: cache-node-modules
47 | with:
48 | # npm cache files are stored in `~/.npm` on Linux/macOS
49 | path: |
50 | ~/.npm
51 | key: ${{ runner.os }}-build-${{ env.cache-name }}-${{ hashFiles('**/package-lock.json') }}
52 | restore-keys: |
53 | ${{ runner.os }}-build-${{ env.cache-name }}-
54 | ${{ runner.os }}-build-
55 | ${{ runner.os }}-
56 | - run: npm install
57 | - run: npm run prettier
58 | eslint:
59 | runs-on: ubuntu-latest
60 | steps:
61 | - uses: actions/checkout@v3
62 | - name: Setup node 14
63 | uses: actions/setup-node@v3.0.0
64 | with:
65 | node-version: 14.x
66 | - name: Cache Node files
67 | uses: actions/cache@v2.1.7
68 | env:
69 | cache-name: cache-node-modules
70 | with:
71 | # npm cache files are stored in `~/.npm` on Linux/macOS
72 | path: |
73 | ~/.npm
74 | key: ${{ runner.os }}-build-${{ env.cache-name }}-${{ hashFiles('**/package-lock.json') }}
75 | restore-keys: |
76 | ${{ runner.os }}-build-${{ env.cache-name }}-
77 | ${{ runner.os }}-build-
78 | ${{ runner.os }}-
79 | - run: npm install
80 | - run: npm run eslint
81 |
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
1 | .vs
2 | node_modules
3 | \[lua\]
4 | .idea
--------------------------------------------------------------------------------
/.idea/jsonSchemas.xml:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 |
22 |
23 |
24 |
--------------------------------------------------------------------------------
/.idea/prettier.xml:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 |
6 |
--------------------------------------------------------------------------------
/.idea/watcherTasks.xml:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 |
6 |
7 |
8 |
9 |
10 |
11 |
12 |
13 |
16 |
17 |
18 |
19 |
20 |
21 |
22 |
23 |
24 |
25 |
--------------------------------------------------------------------------------
/.idea/workspace.xml:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 |
6 |
7 |
8 |
9 |
10 |
11 |
12 |
13 |
14 |
15 |
16 |
17 |
18 |
19 |
20 |
21 |
22 |
23 |
24 |
25 |
26 |
27 |
28 |
29 |
30 |
31 |
32 |
33 |
34 |
35 |
36 |
37 |
38 |
39 |
40 |
41 |
42 |
43 |
44 |
45 |
46 |
--------------------------------------------------------------------------------
/.prettierignore:
--------------------------------------------------------------------------------
1 | .vs
2 | .idea
3 | node_modules
4 | \[lua\]
--------------------------------------------------------------------------------
/.prettierrc.json:
--------------------------------------------------------------------------------
1 | {
2 | "$schema": "https://json.schemastore.org/prettierrc",
3 | "arrowParens": "avoid",
4 | "singleQuote": true,
5 | "trailingComma": "all",
6 | "tabWidth": 4,
7 | "printWidth": 80,
8 | "semi": true
9 | }
10 |
--------------------------------------------------------------------------------
/.vscode/extensions.json:
--------------------------------------------------------------------------------
1 | {
2 | "recommendations": ["gruntfuggly.triggertaskonsave", "redhat.vscode-yaml"]
3 | }
4 |
--------------------------------------------------------------------------------
/.vscode/settings.json:
--------------------------------------------------------------------------------
1 | {
2 | "triggerTaskOnSave.tasks": {
3 | "npm: build": ["src/**/*.ts"]
4 | },
5 | "typescript.tsdk": "node_modules/typescript/lib",
6 | "typescript.preferences.includePackageJsonAutoImports": "on",
7 | "terminal.integrated.defaultProfile.windows": "Command Prompt",
8 | "yaml.schemas": {
9 | "https://raw.githubusercontent.com/mtasa-typescript/mtasa-lua-utils/35c60d06a12b12351df5ce8024880dd77aba63ff/mtasa-meta.schema.json": "mtasa-meta.yml"
10 | },
11 | "redhat.telemetry.enabled": false
12 | }
13 |
--------------------------------------------------------------------------------
/.vscode/tasks.json:
--------------------------------------------------------------------------------
1 | {
2 | "version": "2.0.0",
3 | "tasks": [
4 | {
5 | "type": "npm",
6 | "script": "build",
7 | "problemMatcher": ["$tsc"],
8 | "group": "build",
9 | "label": "npm: build",
10 | "detail": "Run MTASA Project build"
11 | }
12 | ]
13 | }
14 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | # 📄 TypeScript Resource Boilerplate for MTASA
2 |
3 | Write and compile TypeScript into MTASA-compatible Lua code.
4 |
5 | A documentation in your IDE. Types safety. Linting.
6 |
7 | **Features**
8 |
9 | - 🔥 [TypeScriptToLua](https://www.npmjs.com/package/typescript-to-lua)
10 | Provides compilation
11 | - 📓 [MTASA Lua Types](https://www.npmjs.com/package/mtasa-lua-types)
12 | Provides types declarations and the documentation for MTASA functions, variables and classes
13 | - ✅ [MTASA Lua Utils](https://www.npmjs.com/package/mtasa-lua-utils)
14 | Provides code preparation and MTASA specific linting
15 | - ✒️ [Prettier](https://www.npmjs.com/package/prettier)
16 | Code formatter
17 | - 👀 [ESLint](https://eslint.org/)
18 | ESLint for linting TypeScript Code
19 |
20 | # 🎈 Getting started
21 |
22 | ## 💠 NodeJS
23 |
24 | This boilerplate requires NodeJS (at least **14.x**) to be installed.
25 | If you already have NodeJS installed, skip this step.
26 |
27 | Installation for [Windows](https://nodejs.org/en/download/).
28 |
29 | Installation for Linux:
30 |
31 | _Debian or Ubuntu_
32 |
33 | ```shell
34 | apt install nodejs
35 | ```
36 |
37 | _Arch or Manjaro_
38 |
39 | ```shell
40 | pacman -S nodejs
41 | ```
42 |
43 | ### How to check NodeJS installation (and version)
44 |
45 | Open console
46 | [(What?)](https://www.howtogeek.com/235101/10-ways-to-open-the-command-prompt-in-windows-10/#:~:text=Press%20Windows%2BR%20to%20open,open%20an%20administrator%20Command%20Prompt.)
47 | and execute the command
48 |
49 | ```shell
50 | npm version
51 | ```
52 |
53 | ## 🆕 Create new project (initialize boilerplate)
54 |
55 | Open terminal in the parent folder of your new project and run folowwing command:
56 |
57 | ```console
58 | npx mtasa-lua-utils new-project
59 | ```
60 |
61 | 
62 |
63 | ### Structure
64 |
65 | ```
66 | |- .idea/ Configs for WebStorm
67 | |- .github/ Configs for GitHub
68 | |- .vscode/ Configs for VSCode
69 | |- node_modules/ Modules for NodeJS (autogenerated directory)
70 | |- src/ Directory with TypeScript resources
71 | |- TypeScriptResource/ Example Resource
72 | |- types/ Directory with additional types
73 | |- mtasa-meta.yml Description for all resources (meta.xml analog)
74 | ```
75 |
76 | [**All available commands**](https://github.com/mtasa-typescript/mtasa-lua-utils#available-commands)
77 |
78 | ## Compile the project
79 |
80 | Command:
81 |
82 | ```shell
83 | npm run build
84 | ```
85 |
86 | Always running the command to build the resource is annoying.
87 | Below there are possible solutions to simplify it.
88 |
89 | # ✏ Code Editor Preparation
90 |
91 | ## VSCode
92 |
93 | ### Using documentation
94 |
95 | `Ctrl+Mouse Hover` is the shortcut to show documentation window.
96 |
97 | `Ctrl+Shift+Space` is the shortcut to show function's parameters.
98 |
99 | ### Tasks
100 |
101 | Use `Ctrl+Shift+B` and select `npm: build` task to compilte the resource.
102 |
103 | ### Trigger on save
104 |
105 | Plugin [Trigger Task On Save](https://marketplace.visualstudio.com/items?itemName=Gruntfuggly.triggertaskonsave)
106 | should be installed.
107 |
108 | Configuration provided in [.vscode/settings.json](.vscode/settings.json) and will be enabled by default.
109 |
110 | ### YAML Schema
111 |
112 | Plugin [YAML](https://marketplace.visualstudio.com/items?itemName=Gruntfuggly.triggertaskonsave)
113 | should be installed.
114 |
115 | Provides helpful tips for `mtasa-meta.yml` file.
116 |
117 | 
118 |
119 | ## WebStorm
120 |
121 | ### Using documentation
122 |
123 | `Ctrl+Q` is the shortcut to show documentation window.
124 |
125 | `Ctrl+P` is the shortcut to highlight function's parameters.
126 |
127 | ### Configuration
128 |
129 | **NOTE**: In the current version configuration should have been loaded by default.
130 |
131 | In the top right corner press `Edit Configurations`.
132 | Press `Add New Configuration` (Plus icon), select `npm` and select **build** in `Scripts` field.
133 |
134 | 
135 |
136 | Now you can press `Shift+F10` to compile your resource.
137 |
138 | ### File watcher
139 |
140 | **NOTE**: In the current version file watcher should have been loaded by default.
141 |
142 | Compile can be executed after file saving.
143 |
144 | Open `Settings` -> `Tools` -> `File watchers`.
145 | Add new file watcher for TypeScript files in project scope.
146 | Put **npm** into the `Script` field and **run build** into the `Srguments` field.
147 |
148 | 
149 |
150 | Thus, saving after editing TypeScript files triggers compilation.
151 |
152 | # 🚁 Support
153 |
154 | [Discord Server](https://discord.com/invite/67vxSwhRT4)
155 |
--------------------------------------------------------------------------------
/mtasa-meta.yml:
--------------------------------------------------------------------------------
1 | info:
2 | name: TypeScriptResource
3 | type: script
4 |
5 | compilerConfig:
6 | srcDir: TypeScriptResource
7 |
8 | scripts:
9 | - src: client.ts
10 | type: client
11 | cache: false
12 |
13 | - src: server.ts
14 | type: server
15 | cache: false
16 |
17 | - src: utils.ts
18 | type: shared
19 | cache: false
20 | #
21 | # You can add more resources. Use `npm run new-resource`
22 | #
23 |
--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
1 | {
2 | "name": "mtasa_typescript_resource_boilerplate",
3 | "scripts": {
4 | "build": "mtasa-lua-utils build",
5 | "eslint": "eslint --max-warnings=0 .",
6 | "prettier": "prettier --check .",
7 | "prettier-fix": "prettier --write .",
8 | "new-resource": "mtasa-lua-utils new-resource"
9 | },
10 | "devDependencies": {
11 | "@typescript-eslint/eslint-plugin": "^4.30.0",
12 | "@typescript-eslint/parser": "^4.30.0",
13 | "eslint": "^7.32.0",
14 | "mtasa-lua-types": "^1.1.0",
15 | "mtasa-lua-utils": "^1.0.3",
16 | "prettier": "^2.3.2",
17 | "typescript": "~4.5.2",
18 | "typescript-to-lua": "~1.3.4"
19 | }
20 | }
21 |
--------------------------------------------------------------------------------
/src/TypeScriptResource/client.ts:
--------------------------------------------------------------------------------
1 | /**
2 | * File with client-side script example
3 | **/
4 |
5 | import { EventNames } from 'mtasa-lua-types/client/event/all_event_names';
6 | import { Event } from 'mtasa-lua-types/client/mtasa';
7 | import { mtasa } from 'mtasa-lua-types/client';
8 |
9 | mtasa.addEventHandler(
10 | EventNames.OnClientResourceStart,
11 | mtasa.resourceRoot,
12 | function () {
13 | const [hours, minutes] = mtasa.getTime();
14 |
15 | mtasa.outputChatBox(
16 | 'TypeScript Resource Boilerplate works.' +
17 | `In-game time: ${hours}:${minutes}`,
18 | );
19 | },
20 | );
21 |
--------------------------------------------------------------------------------
/src/TypeScriptResource/server.ts:
--------------------------------------------------------------------------------
1 | /**
2 | * File with server-side script example
3 | **/
4 |
5 | import { EventNames } from 'mtasa-lua-types/server/event/all_event_names';
6 | import { Event } from 'mtasa-lua-types/server/mtasa';
7 | import { firstLetterUpperCase } from './utils';
8 | import { mtasa } from 'mtasa-lua-types/server';
9 |
10 | mtasa.addEventHandler(
11 | EventNames.OnPlayerJoin,
12 | mtasa.root,
13 | function () {
14 | const player = mtasa.source as unknown as mtasa.Player;
15 |
16 | const name = firstLetterUpperCase(player.name);
17 | mtasa.outputChatBox(`Welcome, ${name}!`);
18 | },
19 | );
20 |
21 | mtasa.addCommandHandler('typescript-example-command', function (player) {
22 | player.money += 1;
23 | mtasa.outputChatBox(`+1$ to ${player.name}`);
24 | });
25 |
--------------------------------------------------------------------------------
/src/TypeScriptResource/utils.ts:
--------------------------------------------------------------------------------
1 | /**
2 | * File with exported functions example
3 | * (Exported function will be forceful written to _G table)
4 | **/
5 |
6 | export function firstLetterUpperCase(value: string): string {
7 | if (!value) {
8 | return value;
9 | }
10 |
11 | return value[0].toUpperCase() + value.slice(1);
12 | }
13 |
--------------------------------------------------------------------------------
/tsconfig.json:
--------------------------------------------------------------------------------
1 | {
2 | "$schema": "https://raw.githubusercontent.com/TypeScriptToLua/vscode-typescript-to-lua/master/tsconfig-schema.json",
3 | "compilerOptions": {
4 | "target": "ES6",
5 | "lib": ["es6"],
6 | "module": "CommonJS",
7 | "rootDir": "src",
8 | "outDir": "[lua]",
9 | "strict": true,
10 | "sourceMap": true,
11 | "declaration": true,
12 | "noImplicitAny": true,
13 | "noImplicitThis": true,
14 | "noImplicitReturns": true,
15 | "esModuleInterop": true,
16 | "newLine": "LF",
17 | "stripInternal": true,
18 | "baseUrl": ".",
19 | "types": ["lua-types/5.1"]
20 | },
21 | "tstl": {
22 | // MTASA Lua Language version is 5.1
23 | "luaTarget": "5.1",
24 | // No "self" in global functions
25 | "noImplicitSelf": true,
26 | // Provides debug.traceback function
27 | "sourceMapTraceback": true,
28 | // Lualib should be always included in the resource
29 | "luaLibImport": "always"
30 | }
31 | }
32 |
--------------------------------------------------------------------------------
/types/additional.d.ts:
--------------------------------------------------------------------------------
1 | /** You can insert any not declared definitions here (or in another file in this folder)
2 | * If you have any requests, you can easily submit them here:
3 | * https://github.com/mtasa-typescript/mtasa-lua-types/issues
4 | **/
5 |
--------------------------------------------------------------------------------