greybel-vs

This toolkit provides essential tools for developing in GreyScript, the scripting language used in Grey Hack. The extension offers syntax highlighting, code execution, bundling, minification, and more to streamline GreyScript development in VSCode.

Prefer a different editor? The GreyScript Language Server is also available and compatible with IDEs like Sublime Text, IntelliJ, nvim and more. Examples for setting up these editors are included in the repository.

Links

Project Resources

• Changelog: View the latest changes and updates.
• greybel-js CLI: Command-line interface for Greybel.
• GreyScript Documentation: API documentation for GreyScript.

Projects Using Greybel

• minizod: A lightweight, Zod-inspired validation library for MiniScript.
• Viper 3.0: Viper is a hacking shell tool for game named Grey Hack.
• Minesweeper: A Minesweeper game created in GreyScript. (Demo project)
• JSON Parser: JSON parsing functionality. (Demo project)
• TEdit: Text editor built with GreyScript. (Demo project)

Grey Hack Tools

• Image Transformer: Tool for transforming images in Grey Hack.
• Website Image Generator: Tool for generating Grey Hack website images.

Community

• Greybel Discord: Join the community on Discord for support and discussion.

Usage

This extension automatically detects .gs, .src, and .ms files and provides convenient commands to streamline your workflow.

Commands available (CTRL+SHIFT+P):

• Greybel: Build - Transpile your GreyScript code. More info
• Greybel: Share - Share your code with others easily. More info
• Greybel: API - Open the API browser for quick reference. More info
• Greybel: Snippets - Insert GreyScript snippets into your code. More info
• Greybel: Preview output – View a preview of the ingame like output. More info
• Greybel: Import file into the game – Upload files into the game. More info

You can also access these commands through the context menu for quick right-click access:

Tip: Make sure to configure settings to customize Greybel to your preferences.

Settings

• Autocomplete: Activate/Deactivate
• Create in-game
  • Active: Activate/Deactivate
  • Agent: headless, message-hook
  • Mode: local, public
  • Steam User: Steam username
  • Auto Compile: Auto compile and delete source files
  • Allow Import: Enable allowImport on auto compile
• Diagnostic: Activate/Deactivate
• Hoverdocs: Activate/Deactivate
• Formatter: Activate/Deactivate
• Interpreter
  • Default Args: Default call arguments
  • Environment Variables: JSON used to define environment variables (ENVs)
  • Hide Unsupported Text Mesh Pro Rich Text Tags: Hides unsupported rich tags in the pseudo-terminal
  • Seed: Seed used to generate the testing environment
  • Silence Error Popups: Silences error popups due to execution failure
• Transpiler
  • Build Type: Default, Uglify, Beautify
  • Beautify
    • Indentation: Tab or whitespace. What should be used for indentation?
    • Indentation Spaces: In case whitespace is used this will determine the amount of whitespaces.
    • Keep Parentheses: Will always use parentheses.
  • Literals Optimizations: Activate/Deactivate
  • Namespaces Optimizations: Activate/Deactivate
  • Environment Variables: JSON used to define environment variables (ENVs)
  • Excluded Namespaces: List of namespaces that should not be optimized
  • In-game Directory: Destination folder used in the game
  • Installer
    • Active: Activate/Deactivate
    • Auto Compile: Adds boilerplate code to the installer for auto-deletion of the script after execution
    • Allow Import: Enable allowImport when performing auto compile in installer
    • Max Chars: Define the maximum number of characters at which the installer should split the code
  • Obfuscation: Enables minification of namespaces using special characters
• Type Analyzer
  • Strategy: Specifies which files are used for type resolution. The "Dependency" strategy resolves types from all files imported into the current file. Alternatively, the "Workspace" strategy resolves types from all files within the workspace.
  • Exclude: Specifies files to ignore based on matching glob patterns.

Features

• Transform
• Build
• Upload
• Interpreter
• Debugger
• API Browser
• Comment Docs
• Snippets
• Share
• Goto Error
• Preview output
• Providers

Transform

Transpiles your code into a specific format. Be sure to select your desired output in the settings. By default, the "Default" build type is selected.

Output modes

There are three different modes: "Default", "Uglify", and "Beautify". The output will vary depending on the mode selected.

• Default: No special behavior like optimization or formatting. This format is the best all-rounder if you're unsure.

• Uglify: Minifies your code and optimizes literals and namespaces. You can disable these features if necessary, especially if namespaces must remain unchanged for your code to function properly. You can also exclude specific namespaces from optimization.

  

• Beautify: Formats your code to improve readability. There is currently no customizability available in this mode, which might limit its use case.

Imports (Transform)

Important: Unlike the build function, transforms will ignore any #include, #import, or import_code lines. Use the build functionality instead.

Environment (Transform)

Greybel allows you to inject environment variables during transformation. These can be configured in the extension settings.

Build

Building transforms and bundles your scripts in a way that makes them easy to import into Grey Hack. As mentioned in the transform section, building also provides three different output modes: "Default", "Uglify", and "Beautify". For more details, check out the output-modes section.

Auto create files in-game

You can automatically create transpiled files in the game by enabling the "create-ingame" option. Additionally, you can choose between two agents. Depending on the selected agent, there are certain prerequisites to meet and behaviors to consider. Generally it is recommended to use message-hook if possible.

Headless

When using headless mode, you connect to the game without the native game client. Depending on your selected mode, either local or public, the agent will import files into either a single-player or multiplayer session.

By default, local mode is selected. Note that for local to work, the game must have a single-player session running. In public mode, there is no need for the game client to be running.

One important requirement is that a Steam account and password must be provided. The refresh token will be cached, so you won’t need to provide credentials continuously. You can clear the refresh token at any time using the "Clear secrets" command.

Note: This agent may log you out of Grey Hack since the game only allows one active session at a time.

Message Hook

The message-hook agent allows you to send messages to the game server through the game client. To use this feature, you need to first install BepInEx and then the plugin. Below, you can find installation instructions for both versions of BepInEx.

BepInEx 5.x.x

1. 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.
2. Add the Plugin: Download GreyHackMessageHook5.dll and move it to the plugins folder in BepInEx.
3. 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%
4. Launch Grey Hack via Steam to load BepInEx 5 with the plugin.

BepInEx 6.x.x

1. Download BepInEx 6.x.x: BepInEx version 6.0.0-pre.1 UnityMono
   • Install by extracting BepInEx files into your Grey Hack game folder (location of the game executable). See the Installation Guide if needed.
2. Add the Plugin: Download GreyHackMessageHook.dll and move it to the plugins folder in BepInEx.
3. 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%
4. Launch Grey Hack via Steam to load BepInEx 6 with the plugin.

With all that done you can now start the game and start either a single-player or multiplayer session. You'll be now able to sync files with the game without getting disconnected.

Also, keep in mind that if you use BepInEx 6.x.x you'll use bleeding edge meaning that it won't be as stable as BepInEx 5.x.x leading to potential crashes. If you suffer too many crashes with 6.x.x may try out version 5.x.x!

Additionally, you won't need to provide any Steam credentials nor do you need to select a mode.

Note: For this agent to work you have to have Grey Hack running.

Imports on building

Scripting in Grey Hack can be challenging, especially when you have files that import each other or are working on a larger project where you have to copy-paste each file manually into the game every time. Greybel aims to reduce this hassle, allowing you to spend more time coding and playing rather than copy-pasting files repeatedly.

Dependency Management (Transpiler)

Greybel enables you to split your code into different files, which helps maintain readability and also makes your code reusable.

It is recommended to use include and import for small or medium-sized projects.

For larger projects, import_code should be used instead, as the transpiler will bundle your files in a way that maximizes the use of import_code in the game, helping to avoid exceeding the maximum character limit of 160,000.

Cyclic dependencies will also be detected. If a cyclic dependency is found, an error will be thrown, indicating which file is causing it.

A step-by-step guide is available here.

Import

Used to import exported namespaces from a file. Features:

• Supports relative imports
• Loads code only when required
• Does not pollute global scope
• Only imports once, no matter how many times it’s referenced
• Exports only what you want
• Code is appended to the root file, which may exceed the character limit in GreyHack. If that's an issue, use import_code instead

You can check out the example code for a better understanding of how to use this feature.

Include

Used to import the content of a file. Features:

• Supports relative includes
• Easy to use
• Pollutes global scope
• Includes the content every time, which may lead to redundant code
• May exceed the character limit of GreyHack, so use import_code instead if this is a concern

You can review the example code for more details.

import_code

Used to import code from a file. Features:

• Keeps files separate in-game, helping to avoid the character limit
• Supports nested import_code
• Supports relative imports

Here’s some example code.

When the installer option is enabled, Greybel will create one or more installer files depending on the size of your project. These installer files will contain all the code files and logic to create the files in the game. Essentially, you just need to copy and paste the installer code into the game, then compile and execute it. Using the --auto-compile flag adds logic to automatically compile the project and remove all source files.

By setting up the in-game directory in the settings, you can define where you want the files to be imported in the game. By default, /root/ is used.

Additionally, nested import_code is supported. This is achieved by moving all imports into the entry file based on their usage throughout the project. It’s recommended to only use import_code at the head of the file, as the import locations of nested files cannot be guaranteed.

Syntax

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

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. This 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. This 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 define an environment variable for the provided namespace. If no value is 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. If the file does not exist, it will be replaced with null. Content injected will automatically be escaped.

Upload

If you're not interested in the build functionality or need to upload many files into the game, you can use the "Import files into game" command. This will behave similarly to the create-in-game build feature, but without the building step.

This feature will also use the transpiler's "Ingame directory" setting as the in-game destination.

IMPORTANT: Please read about the two available agent options headless and message-hook. It is recommended to use message-hook but it requires to setup BepInEx.

Interpreter

Greybel comes with its own GreyScript interpreter, allowing you to test and debug your code outside of the game. This is partly due to the test environment that gets generated on the fly, attempting to emulate the game's API.

Dependency Management (Interpreter)

Dependencies are dynamically loaded into the execution without any limitations. Cyclic dependencies are also supported.

Environment Variables (Interpreter)

Greybel supports the injection of environment variables into the interpreter. These environment variables can be configured in the extension settings.

Local Environment

Greybel GreyHack Intrinsics will automatically generate a local environment. It will also generate other computers, networks, filesystems, etc., on the fly. By default, generation is based on a seed called test. This seed can be modified using the seed option. Using the same seed will ensure that generated entities remain consistent.

The local computer setup is hardcoded. The admin credentials are root:test. You will also have crypto.so and metaxploit.so available on your local computer.

Examples:

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

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

Greyscript API support

The intrinsics to support the Greyscript API are provided by Greybel Intrinsics and Greybel GreyHack Intrinsics. Keep in mind that not all of these functions are completely mocked. Also, only API that is available in the stable build will be implemented.

Not yet supported:

• AptClient - only polyfill which "returns not yet supported"
• Blockchain - only polyfill which "returns not yet supported"
• Wallet - only polyfill which "returns not yet supported"
• SubWallet - only polyfill which "returns not yet supported"
• Coin - only polyfill which "returns not yet supported"

TextMesh Pro Rich Text Support

TextMesh Pro Rich Text is partially supported.

Note: For the pseudo-terminal, Greybel will attempt to transform TextMesh Pro Rich-Text tags into ANSI codes. Due to the nature of TextMesh Pro Rich-Text tags, some formatting may be lost. If you're looking for a proper preview of your output in Grey Hack, please check out the Preview Output feature.

Debugger

The debugger allows you to set breakpoints, run code in a breakpoint context, and jump to the next line of execution. It's helpful for debugging your code.

Note: Make sure to set the breakpoint on a non-empty line, or it will be skipped.

A REPL is also available while executing the script or having an active breakpoint.

Preview Output

This feature creates a web view that renders actual TextMesh Pro Rich-Text tags within VSCode. Its main purpose is to emulate the actual output of the game, making it useful for drawing images or creating fancy prompts.

API Browser

The API Browser for GreyScript brings the GreyScript API Documentation directly into Visual Studio Code.

Comment Docs

Provide signatures for your functions to show better hover tooltips. Additionally, the provided return value will be recognized by the implemented type system, resulting in context-sensitive auto-complete suggestions.

// Hello world
// I am **bold**
// @description Alternative description
// @example test("title", 123)
// @param {string} title - The title of the book.
// @param {string|number} author - The author of the book.
// @return {crypto} - Some info about return
test = function(test, abc)
  print(test)
end function

There is also the possibility of custom types. Here an example:

// @type Bar
// @property {string} virtualMoo
// @property {string} nested.virtalMoo
Bar = {}
Bar.moo = ""

// Hello world
// I am **bold**
// @description Alternative description
// @example test("title", 123)
// @param {string} title - The title of the book.
// @param {string|number} author - The author of the book.
// @return {Bar} - Some info about return
Bar.test = function(test, abc)
	print("test")
	return self
end function

// @type Foo
Foo = new Bar
// @return {Foo}
Foo.New = function(message)
	result = new Foo
	return result
end function

myVar = Foo.New

myVar.test // shows defined signature of Bar.test on hover
myVar.virtualMoo // shows virtual property of type string on hover
myVar.nested.virtalMoo // shows nested virtual property of type string on hover

Share

Shares your code via editor.greyscript.org. The related link will be copied to your clipboard.

Snippets

Provides a list of available GreyHack snippets, such as ls, mkdir, and more.

Goto Error

Jumps to the next existing syntax error.

Supporting Providers

This extension includes several IntelliSense providers to enhance your coding experience with GreyScript:

• Autocompletion Provider
  Offers context-aware suggestions based on your current position in the code.

• Signature Helper Provider
  Displays function signatures with parameter types and return values as you type, helping you use functions correctly and efficiently without needing to reference documentation.

• Hover Tooltips Provider
  Displays helpful information about functions and types when you hover over them.

• Diagnostics Provider
  Identifies and highlights syntax errors in your code for easier debugging.

• Symbol Provider
  Lists all symbols available in the active file for easy navigation.
  

• Definition Provider
  Locates and displays definitions within the active file and its dependencies.
  

• Color Picker Provider
  Shows a color picker when you use color or mark tags in your code.

Copyright

Sloth icons created by Freepik - Flaticon

Todo

• implement missing intrinsics
• improve mock environment

Contact

For questions, feature requests, or support, feel free to join the dedicated Greybel Discord.