greybel-js

Greybel-JS

CLI that provides a set of tools for working with GreyScript. GreyScript is a scripting language used within GreyHack.

Links

Project Resources

• Changelog: View the latest changes and updates.
• greybel-js CLI: Command-line interface for Greybel.
• GreyScript Documentation: API documentation for GreyScript.
• Greybel UI Demo: Online editor to write specifically GreyScript.
• VSCode Extension: VSCode extension for GreyScript.
• Language server: LSP supporting GreyScript.

Projects Using Greybel

• gsse: GreyScript Script Extender is a modular library that aims to expand the current scripting framework of greyscript.
• minizod: A lightweight, Zod-inspired validation library for MiniScript.
• Pocket Creatures: A Pokemon-like game created in GreyScript. (Demo project)
• Minesweeper: A Minesweeper game created in GreyScript. (Demo project)
• JSON Parser: JSON parsing functionality. (Demo project)
• TEdit: Text editor built with GreyScript. (Demo project)

Do you have a project that uses Greybel? If so, feel free to create a pull request to showcase it here.

Grey Hack Tools

• GreyHack Terminal UI: A mod that extends GreyScript capabilities, allowing you to create custom GUI programs in both Singleplayer and Multiplayer.
• Image Transformer: Tool for transforming images in Grey Hack.
• Website Image Generator: Tool for generating Grey Hack website images.

Community

• awesome-greyhack: List with several resources related to Grey Hack.
• Greybel Discord: Join the community on Discord for support and discussion.

Features

• Easily manage imports for small and large projects

  • Import files directly into the game without needing to copy-paste
  • Handle dependencies between different code files
  • Use environment variables during the transpilation process
  • Syntax enhancements for easier coding
  • Minimize your scripts to save up to 40% on large projects
    • Optimize literals (strings, booleans, numbers)
    • Minify namespace names
    • Remove unnecessary whitespace and tabs
    • Obfuscate code (as a side effect of the above optimizations)
  • Beautify your code for easier readability (helpful for deobfuscation)

• Run and test your code outside of GreyHack

  • Manage file dependencies in the interpreter
  • Simulate a local mock environment for testing
  • Full support for the GreyScript API
  • Debug your code with ease
  • Support for TextMesh Pro Rich Text
  • Use environment variables in your code execution

• Interactive REPL for GreyScript

  • Easily experiment with your code in a live environment

• Web UI for enhanced coding experience

  • Share your code easily
  • Save your work directly in the web interface
  • Debug your code within the web UI
  • TextMesh Pro Rich Text support in the web UI

Install

npm i -g greybel-js

Transpiler

Transpiler CLI
Example: greybel build <myscriptfile> [output]

Arguments:
	filepath                    File to compile
	output                      Output directory

Options:
  -V, --version                                  output the version number
  -si, --silence                                 Silences any uncessary noise.
  -fe, --file-extensions <extension...>          Define allowed file extensions.
  -ev, --env-files <file...>                     Specifiy environment variables file.
  -vr, --env-vars <var...>                       Specifiy environment variable definition.
  -en, --exclude-namespaces <namespace...>       Exclude namespaces from optimization. This option is only used in combination with uglifying.
  -dlo, --disable-literals-optimization          Disable literals optimization. This option is only used in combination with uglifying.
  -dno, --disable-namespaces-optimization        Disable namespace optimization. This option is only used in combination with uglifying.
  -u, --uglify                                   Minify your code.
  -b, --beautify                                 Beautify your code.
  -o, --obfuscation                              Allows the namespace optimization to use a wider range of characters in order to safe more
                                                 space.
  -id, --ingame-directory <ingameDirectory>      In-game directory target path.
  -i, --installer                                Create installer for GreyScript. Only use this option when there is at least one import_code
                                                 in place.
  -mc, --max-chars <number>                      Max amount of characters allowed per file. Installer files will be split depending on the
                                                 amount defined in this option. By default the maximum is 160k chars.
  -ac, --auto-compile                            Enables auto-compile within the installer or create-ingame feature. This option will also
                                                 delete all files in-game after building.
  -ai, --allow-import                            Enables allowImport on auto-compile.
  -acp, --auto-compile-purge                     Specify this option if you would like all of the imported folders to be deleted after the
                                                 auto-compilation process is completed regardless of any files may remaining in those folders.
  -ci, --create-ingame                           Enable transfer of your code files into Grey Hack.
  -pt, --port <port>                             Set connection port for message-hook. (only relevant when using --create-ingame)
  -dbf, --disable-build-folder                   Disable the default behaviour of putting the output into a build folder. It will instead just
                                                 put it wherever you set the output destination to.
  -of, --outputFilename <name>                   Specify the name of the main output file.
  -h, --help                                     display help for command

Examples:

Most common build command:

greybel build /my/code/file.src

Auto Create Files In-Game

You can automatically create transpiled files directly in the game using the --create-ingame flag. To use it, you must have message-hook installed.

Dependency Management (Transpiler)

Greybel allows you to split your code into multiple files, improving readability and making code reusable.

For small or medium-sized projects, it’s recommended to use include and import. For larger projects, use import_code to avoid exceeding the 160,000 character limit in GreyHack, as the transpiler bundles your files efficiently.

Greybel also detects cyclic dependencies, throwing an error with the problematic file.

For a detailed guide, refer to this page.

Import

Imports exported namespaces from another file with these features:

• Supports relative imports
• Loads code only when required
• Doesn’t pollute the global scope
• Only imported once, no matter how many times referenced
• Exports only what is needed
• Appends code to the root file (may exceed GreyHack’s character limit; use import_code if this is an issue)

For an example, check out the sample code.

Include

Imports the content of a file with these features:

• Supports relative includes
• Easy to use
• Pollutes the global scope
• Includes the file content every time, which may cause redundancy
• Could exceed the character limit in GreyHack; use import_code instead

For an example, check out the sample code.

import_code

Imports code from a file with these features:

• Keeps files separate in-game, preventing the character limit issue
• Supports nested import_code
• Supports relative imports

For an example, check out the sample code.

When using the --installer flag, Greybel creates installer files for your project. These files bundle all your code and logic for easy pasting into the game. After that, you can compile and execute them. The --auto-compile flag adds automatic compilation and source file removal.

You can also specify an in-game directory using the --ingame-directory CLI parameter, with /root/ as the default.

Note: Nested import_code is supported. It’s recommended to place import_code at the top of files, as the import order of nested files is not guaranteed.

Environment Variables (Transpiler)

Greybel supports the injection of environment variables while transpiling. There are two ways of environment variables.

• Use the --env-files CLI parameter to define environment variables configuration files.
• Use the --env-vars TEST="hello world" CLI parameter to define variables on the fly.

Here is an example of environment variable injection.

Syntax

Any valid MiniScript or GreyScript syntax is supported. Additionally, some minor syntax sugar is added to those languages. If you use those keep in mind to transpile your code first. Using these is completely optional though.

No trailing comma is required in maps or lists

myList = [
	false,
	null
]

myMap = {
	"test": {
		"level2": {
			"bar": true
		}
	}
}

Math - shorthand

a /= b
a *= b
a -= b
a += b

Bitwise - shorthand

a = b << c
a = b >> c
a = b >>> c
a = b | c
a = b & c

Block comment

/*
	My block comment
*/
print("test")

Filename expression

print(#filename)

The filename expression will be replaced with the string literal containing the name of the file before transpiling. Can be useful for debugging.

Line expression

print(#line)

The line expression will be replaced with the number literal containing the line of the expression before transpiling. Can be useful for debugging.

Envar expression

print(#envar MY_TEST_VAR)

The envar expression will be replaced with the value of the provided environment variable. Make sure you defined an environment variable for the provided namespace if there is no value found it will instead use null.

Inject expression

print(#inject "path/to/file")

The inject expression will be replaced with the content of whatever file exists at the provided path. In case the file does not exist it will be replaced with null. Content that gets injected will automatically be escaped.

Interpreter

Interpreter CLI
Example: greybel execute <myscriptfile>

Arguments:
	myscriptfile			File to execute

Options:
  -p, --params <params...>                Defines params used in script execution.
  -i, --interactive                       Enter params in interactive mode instead of arguments.
  -d, --debug                             Enable debug mode which will cause to stop at debugger statements.
  -s, --seed <seed>                       Define seed value which is used to generate entities. (only relevant when using Mock environment)
  -ev, --env-files <file...>              Specifiy environment variables file.
  -vr, --env-vars <var...>                Specifiy environment variable definition.
  -si, --silent                           Silences any uncessary noise.
  -et, --env-type <type>                  Set interpreter environment. (mock, in-game)
  -pt, --port <port>                      Set connection port for message-hook. (only relevant when using In-Game environment)
  -pg, --programName <name>               Set program name used in runtime. (only relevant when using In-Game environment)
  -fe, --file-extensions <extension...>   Define allowed file extensions.
  -h, --help                              display help for command

For Windows, you can use something like PowerShell or ConEmu. Or just use the UI. GitBash is not recommended due to a TTY issue with node.

Dependency Management (Interpreter)

Dependencies will be dynamically loaded into the execution without any limitations. Cyclic dependencies are supported as well.

Environment Variables (Interpreter)

Greybel supports the injection of environment variables for the interpreter as well. The way CLI parameters are used is identical to the ones of transpiling.

• Use the --env-files CLI parameter to define environment variables configuration files.
• Use the --env-vars TEST="hello world" CLI parameter to define variables on the fly.

Here is an example of environment variable injection.

Mock Environment

When using this environment, Greybel will automatically generate a local setup, including simulated computers, networks, filesystems, and more, on the fly. By default, generation is based on a seed value called test. You can modify this seed using the appropriate option. Using the same seed consistently will ensure that the generated entities remain stable across sessions.

The local computer configuration is hardcoded, with admin credentials set to root:test. Additionally, your local machine will have crypto.so and metaxploit.so available by default.

Note that the mock environment runs locally and is independent from the actual game. As a result, some intrinsic game behaviors may not be fully supported. If you need highly accurate debugging, consider using the In-game Environment instead.

Examples:

metax = include_lib("/lib/metaxploit.so") //returns metaxploit interface
print(metax) //prints metaxploit

myShell = get_shell("root", "test") //get local root shell

Ingame Environment

This environment uses the actual in-game setup. To use it, you must have message-hook installed and the game running in singleplayer mode.

The key advantage of the in-game environment is that it mirrors real gameplay behavior exactly, unlike the mock environment, which is an approximation.

Debugger (CLI)

Pauses execution and enables you to inspect/debug your code. Additionally, you'll be able to inject code.

index = 1
print("Hello world!")
debugger
print("Another string!")

TextMesh Pro Rich Text support (CLI)

TextMesh Pro Rich Text is partially supported.

Supports

• color
• mark
• underline
• italic
• bold
• strikethrough
• lowercase
• uppercase

Note: For the CLI feature Greybel will try to transform TextMesh Pro Rich-Text tags into ANSI-Codes. Due to the nature of TextMesh Pro Rich-Text tags some formatting will get lost. If you are looking for a proper preview of your output in Grey Hack please check out the preview output feature from the VSCode extension.

TestLib

Adds testing methods for setting up envs and debugging. Keep in mind that this library is not available in the actual game.

testLib = include("/lib/testlib.so")

// returns all active shell sessions
sessions = testLib.sessions

// can be used to generate routers, get_router will do the same
router = testLib.get_or_create_router("12.12.12.12")

// can be used to get all computers with root access which are related to router
computers = testLib.get_computers_connected_to_router(router)
computer = computers.values[0]

// can be used to receive root shell of certain computer
shell = testLib.get_shell_for_computer(computer)

// can be used to receive root shell of certain file
shell = testLib.get_shell_for_file(computer.File("/lib"))

// can be used to receive computer with root access of certain file
computer = testLib.get_computer_for_file(computer.File("/lib"))

// can be used for debugging purposes, will return current stack trace
test = function
	print(testLib.get_stack_trace)
end function

test

Import

Import CLI
Example: greybel import <myscriptfile>

Arguments:
	targetpath                  File or folder to import

Options:
  -V, --version                                  output the version number
  -id, --ingame-directory <ingameDirectory>      In-game directory target path.
  -pt, --port <port>                             Set connection port for message-hook.
  -h, --help                                     display help for command

IMPORTANT: Please keep in mind that you first need to setup the message-hook agent.

REPL

REPL CLI
Example: greybel repl

For Windows, you can use something like PowerShell or ConEmu. Or just use the UI. GitBash is not recommended any more due to a TTY issue with node.

REPL also features a local environment and GreyScript API support

Web-UI

Web UI CLI
Example: greybel ui

Simple UI which can be used for minifying and executing code. There is also a VSCode extension which includes a lot of neat features. Like for example a debugger with breakpoints etc.

Share code

This functionality can be used to share code with others without saving it. Keep in mind that the URL might become very long and may even exceed the URI size accepted by the online UI. If you want to share code without this limitation use the save code functionality instead.

Save code

This functionality can be used to save and also share code with others. Every time save is pressed a new id will get generated and appended to the browser URL which enables you to just copy and paste the URL and share your code with others.

Debugger (Web-UI)

TextMesh Pro Rich Text support (Web-UI)

TextMesh Pro Rich Text is partially supported.

Supports

• color
• mark
• underline
• italic
• bold
• strikethrough
• lowercase
• uppercase
• align
• cspace
• lineheight
• margin
• nobr
• pos
• size
• voffset
• indent

Note: For the UI feature Greybel will try to transform TextMesh Pro Rich-Text tags into HTML. But due to the nature of TextMesh Pro Rich-Text tags some formatting will get lost. If you are looking for a proper preview of your output in Grey Hack please check out the preview output feature from the VSCode extension.

Message Hook

The Message Hook enables Greybel to communicate with the game server via the game client, extending its functionality. Features such as in-game auto-create (used for building) and the in-game interpreter environment rely on this capability. Installing it is entirely optional and not required for basic use.

To use the Message Hook, you must first install BepInEx, followed by the appropriate plugin. Instructions are provided below for both BepInEx 5.x.x and 6.x.x versions.

Note: BepInEx 6.x.x is in a pre-release state and may be less stable than 5.x.x. If you experience frequent crashes, consider switching back to version 5.x.x.

BepInEx 5.x.x

• Download BepInEx 5.x.x: BepInEx v5.4.23.2
  • Install by extracting BepInEx files into your Grey Hack game folder (location of the game executable). See the Installation Guide if needed.
• Add the Plugin: Download GreyHackMessageHook5.dll and move it to the plugins folder in BepInEx.
• Configure Launch Options (macOS/Linux Only):
  • Go to Steam Library > Grey Hack > Properties > Launch Options.
    • macOS: "/path/to/Steam/steamapps/common/Grey Hack/run_bepinex.sh" %command%
    • Linux: "/path/to/.steam/steam/steamapps/common/Grey Hack/run_bepinex.sh" || %command%
• Launch Grey Hack via Steam to load BepInEx 5 with the plugin.

BepInEx 6.x.x

• Download BepInEx 6.x.x: BepInEx version 6.0.0-pre.2 Unity.Mono
  • Install by extracting BepInEx files into your Grey Hack game folder (location of the game executable). See the Installation Guide if needed.
• Add the Plugin: Download GreyHackMessageHook.dll and move it to the plugins folder in BepInEx.
• Configure Launch Options (macOS/Linux Only):
  • Go to Steam Library > Grey Hack > Properties > Launch Options.
    • macOS: "/path/to/Steam/steamapps/common/Grey Hack/run_bepinex.sh" %command%
    • Linux: "/path/to/.steam/steam/steamapps/common/Grey Hack/run_bepinex.sh" || %command%
• Launch Grey Hack via Steam to load BepInEx 6 with the plugin.

Troubleshooting

Grey Hack is crashing on startup on macOS (Apple Silicon)

Since version 0.9.5694, Grey Hack runs natively on Apple Silicon Macs. When used with BepInEx, this can cause crashes, specifically the following error:

EntryPointNotFoundException: SteamInternal_SteamAPI_Init assembly:<unknown assembly> type:<unknown type> member:(null)
  at (wrapper managed-to-native) Steamworks.SteamAPI+Native.SteamInternal_SteamAPI_Init(string,intptr)
  at Steamworks.SteamAPI.Init (System.String pszInternalCheckInterfaceVersions, System.String& pOutErrMsg) [0x0000e] in <6edbf121be6b4184ba49a762e217ee3b>:0 
  at Steamworks.SteamClient.Init (System.UInt32 appid, System.Boolean asyncCallbacks) [0x000f4] in <6edbf121be6b4184ba49a762e217ee3b>:0 
  at ClientSteam.Start () [0x0001e] in <5900bf36cb6f404fa6809df9b65e2cde>:0 
UnityEngine.DebugLogHandler:Internal_LogException(Exception, Object)
UnityEngine.DebugLogHandler:LogException(Exception, Object)
UnityEngine.Logger:LogException(Exception, Object)
UnityEngine.Debug:LogException(Exception)
ClientSteam:Start()

You can fix this crash by deleting the libsteam_api.dylib file located in the game's root directory. This crash is caused by multiple versions of libsteam_api.dylib being present, leading to the wrong library loading first. Deleting the duplicate libsteam_api.dylib in the game root prevents this conflict, allowing the correct version to load. This fix does not appear to affect gameplay or functionality.

Contact

If you have any questions, feature requests or need help feel free to join the dedicated Greybel Discord.