hedgefog / node-amxxpack Goto Github PK

View Code? Open in Web Editor NEW

15.0 3.0 1.0 1.16 MB

🇺🇦 📦 AMXXPack - CLI and build system for amxx projects

License: MIT License

TypeScript 95.85% JavaScript 4.15%

amxmodx cli builder amxx pawn amxxpack npm

node-amxxpack's Introduction

📦 AMXXPack 🇺🇦

Simple build system and CLI for AMX Mod X projects.

📄 About

This system will be useful for projects with multiple plugins and assets. Using the command-line interface you can build an entire project with a single command. It also supports hot rebuild to keep your plugins and assets up to date during the work.

📚 Features

⚙ Flexible configuration
🔥 Hot reload
🧸 Assets builder

🔄Requirements

Node.js 10.0.0+

🔧 Installation

AMXXPack is available through the npm registry. Installation can be done using the npm install command:

npm install amxxpack

or install it globally to use as a system command

npm install -g amxxpack

▶ Quick start

Open a terminal inside the project directory (existing or create a new one)
Execute npm install amxxpack -g command to install amxxpack globally
Execute amxxpack create . command to create a new config
Execute amxxpack install to download project dependencies (compiler, thirdparty etc.)
Use amxxpack build command to build the project
Use amxxpack watch command to build the project and watch changes

📋 Commands

amxxpack create <name> - create new project
- --git - initialize git
- --nonpm - don't initialize the npm package
- --version - project version
- --author - project author
- --description - project name
amxxpack config - initialize project config in the current workspace
amxxpack install - install project dependencies
- --config - config file
amxxpack build - command to build the project
- --watch - flag to watch changes
- --config - config file
- --ignore - ignore build errors
- --no-cache - disable caching
amxxpack compile <path|glob> - compile specific plugin in the project
- --config - config file
- --no-cache - disable caching
amxxpack generate <script|lib|include> [name] - create a new file in the project workspace
- --config - config file
- --name - plugin name
- --version - plugin version
- --author - plugin author
- --lib - library name
- --include - include list separated by a comma
- --overwrite - overwrite the file if it already exists
amxxpack cache clean - clean amxxpack cache
amxpack i - alias to install command
amxpack g - alias to generate command
amxpack b - alias to build command
amxpack c - alias to compile command

🦸 Advanced configuration

Third-party dependencies

In case your project requires third-party modules you can specify a link to third-party archives and these archives will be downloaded and extracted to the third-party directory.

{
  "thirdparty": {
    "dir": "./.thirdparty",
    "dependencies": [
      {
        "name": "somemodule",
        "url": "https://website/somemodule-v100.zip"
      }
    ]
  }
}

the configuration above will download somemodule-v100.zip archive and extract it to the ./.thirdparty/somemodule directory then you can use thirparty files in your project. For example, add a third-party directory to the include list:

{
    "include": [
      "./.thirdparty/somemodule/include"
    ]
}

Multiple directories as an input

You can use multiple directories as builder inputs, just specify an array of directories in the project configuration. Example:

  {
    "input": {
      "scripts": ["./src/scripts", "./src/extra-scripts"],
      "include": ["./src/include", "./src/extra-include"],
      "assets": ["./assets", "./extra-assets"]
    }
  }

Disabling output

Use null value for outputs to disable copying of specific output.

For example, in this case, include files will not be copied to the output folder:

  {
    "output": {
      "include": null
    }
  }

Assets filtering and subdirectories

Using glob filters you can specify which assets should be copied.

For example, you can exclude all assets except *.mdl:

  {
    "input": {
      "assets": [
        { "dir": "./assets", "filter": "*.mdl" }
      ]
    }
  }

or exclude *.tga and *.wav files:

  {
    "input": {
      "assets": [
        { "dir": "./assets", "filter": "*.!(tga|wav)" }
      ]
    }
  }

You can also specify subdirectories for copying. With this configuration, the builder will copy all files from ./assets/models to ./models/myproject of the project build directory.

  {
    "input": {
      "assets": [
        { "dir": "./assets/models", "dest": "./models/myproject" }
      ]
    }
  }

Compiler configuration

Using the compiler configuration you can specify the compiler version you want to use.

For example, if you want to use AmxModX 1.9 with cstrike addon in your project, then use this configuration:

{
  "compiler": {
    "version": "1.9",
    "addons": ["cstrike"]
  }
}

In case you want to use a dev build from amxxdrop you should set dev flag to true and specify the build you want to use in the version field:

{
  "compiler": {
    "version": "1.10.0-git5467",
    "dev": true,
    "addons": ["cstrike"]
  }
}

node-amxxpack's People

Contributors

Stargazers

Watchers

Forkers

rtxa

node-amxxpack's Issues

Can't disable copy of scripts and include

Hi Mr. Hedgefog, thanks a lot for the new features and for having adressed some the issues I have posted, I didn't have the time to test them because I wasn't into AMXX development anymore by that time.

Removing or leaving empty the variables scripts or include on the output section will not disable the copying of these files on the dist default folder.

My proposed solution will be the same as in #3, when the string is empty '' or not provided in the file, then disable the copying.

The feature is useful if you're just planning on only distributing compiled binaries, or you're just using the hot-reload feature (my case).

Cache files to avoid rebuilding the entire project

Sometimes when your project has a lot of resources (like models, sounds, maps), the building process will get a slowdown.
It will be useful to cache the files for the next amxxpack build command call to avoid wasting any precious time and save it only for the compiling part.

The command amxxpack build --watch help with this issue but the caching is only stored in-memory and not in the disk storage, as soon as you stop the task for some reason, you have to go back to the rebuilding process again.

Maybe this article can help you with this: https://medium.com/@wlarch/avoid-long-running-and-killed-gulp-tasks-with-this-simple-caching-gulp-plugin-67ec8bbf466b

Do not waste time during your build process when there is no reason to.

This plugin will process all files in gulp.src() if at least one file was changed. This plugin uses the features of node-file-cache to keep track of the assets SHA1 hashed content in a cache.json file.

Make the assets configuration more powerful

Right now the way the assets are copied works fine for simple projects, it will just copy the entire folder. But for more complex projects, it will be useful to have the ability to exclude some folders, to add more folders for copying, maybe the ability to avoid copying sub-dirs inside that dir. Doing this will avoid the necessity to use external scripts.

To put it more clear, these are some of the options I would like to see implemented:

Exclude folders for copying
Being able to add more folders for copying
Have the ability to choose if we need to copy also subdirs
Limit copying by file extension.

For example, I have my project (AG Mod X) which has assets like maps, models and sprites which are fine for those, but I have too files that are platform dependent like the server binaries (custom DLLs, Metamod, etc.). We need to have the ability to export assets by platform, like having two folders inside dist, one for Windows for Linux. Right now this stops me from using AMXXPack to its full potential.

How can this be implemented? I'm not sure, maybe I can give a draft how this will look inside the .amxxpack.json if you are interested.

Improve docs on how to use different AMXX compiler versions

It would be useful to make clear that information to newcorners because right now I'm not sure exactly how to set up the AMXX compiler to version 1.10 - build 5465. I read somewhere in the official thread in alliedmods that is not longer necessary to specify the complete build, but README.MD doesn't specify that.

[Question] Is there a way to display errors/warnings in 'Problems' tab on VSCode?

I wonder if it's possible to show the the errors/warnings in Problems tab on VSCode. I see that I can't go to the error code line by pressing CTRL while clicking in 836. Probably is mising the : at the beggining which will make it a line search. Not sure if this requires modifications on Klyppy AMXXPawn extension.

Allow to disable some config options in .amxxpack.json

When the project is not gonna use some of the config options (like assets), you probably will try to disable it by making the field empty or removing it. This currently is not possible and it will trigger an error with the parser in resolve.js

For example, you just want to build the .sma files only, then when everything is ready, you build the entire project with the assets included.

A possible fix for this problem would be to provide a default value for these options (to avoid triggering an error when the field isn't isn't defined), and to check that when it's empty, don't do any copying.

// --------------- Case 1 -------------------
"input": {
    "scripts": "./src/scripts",
    "include": "./src/include",
    "assets": "" // Leaving this empty will use the "node_modules" folder instead.
},
"output": {
    "scripts": "./dist/addons/amxmodx/scripting",
    "plugins": "./dist/addons/amxmodx/plugins",
    "include": "./dist/addons/amxmodx/scripting/include",
    "assets": "./dist"
},

// ------------ Case 2 -------------------
"input": {
    "scripts": "./src/scripts",
    "include": "./src/include",
    // Removing the field will trigger a parser error
    // "assets": ""
},
"output": {
    "scripts": "./dist/addons/amxmodx/scripting",
    "plugins": "./dist/addons/amxmodx/plugins",
    "include": "./dist/addons/amxmodx/scripting/include",
    // Removing the field will trigger a parser error
    // "assets": ""
},

This can be workarounded to input to some empty directory like "assets": "./empty", but still it would be good to be able to disable this.

Some options I found useful to disable by the moment are:

assets in both input/output: Sometimes you want to disable temporarily the copying of the assets
output.scripts: Sometimes you don't need to distribute the scripting files

Skip bad plugins when building

The whole assembly breaks off if at least 1 plugin is not approved by the compiler (Compilation aborted...). It is extremely inconvenient when building a large project - I would like to skip such plugins and continue building the following plugins.