Skip to content

Creating external program

Jump to bottom
AlexALX edited this page Aug 24, 2026 · 10 revisions

Creating an External Program (Remote / Isolated)

This page explains how to create and execute independent, external Expression2 programs within ALX OS using a Remote Executor expansion board.

Unlike Embedded Programs, external programs do not require modifying the core CPU/GPU chips or rebuilding the OS. They run in an isolated environment directly on the hardware module.

Mandatory Requirements

This functionality relies entirely on the Wiremod E2 remoteupload extension. Before proceeding, ensure that this extension is enabled on the server via the console command:

wire_expression2_extension_enable remoteupload

If this extension is disabled, the Remote Executor board will not function.

Hardware Setup

  1. Spawn a Remote Executor board (located inside advdupe2 under alx_pc/parts).
  2. Install the component into an available PCI slot on the ALX PC motherboard.

E2 Execution Formats: .e2r vs .e2p vs .e2z

ALX OS supports three ways to execute external code through the Remote Executor. The choice depends on whether the code is raw script with not includes, a direct local path, or bundled inside a compressed package with custom assets and includes support.

1. Remote Source Format (.e2r)

  • How it works: ALX OS reads the file containing a full Expression2 source code and executes it via the Remote Executor using remoteupload. No includes supported.

  • Deployment Steps:

  1. Copy your E2 script from garrysmod/data/expression2/ (e.g. alx_pc/gpu/remote/testprog.txt) into your local folder garrysmod/data/e2files/.
  2. Inside ALX OS, create a file named testprog.e2r.
  3. Set its content to point to your local file: file://testprog.txt.
  4. Run the .e2r file.

Note: Any #include will cause an error! This must be totally self-contained, isolated code.

2. Path-based Execution Format (.e2p)

  • How it works: The file contains a direct string path pointing to an E2 file already located inside the garrysmod/data/expression2/ directory. The Remote Executor runs it directly from your machine.

  • Deployment Steps:

  1. Inside ALX OS, create a file named testprog.e2p.
  2. Set its content as alx_pc/remote/testprog_e2p.txt (relative to garrysmod/data/expression2/). This is just a string value with path NOT actual code!
  3. Run the .e2p file.

Critical Note: For .e2p execution, you must add #include "alx_pc/remote/e2p_include" in your code. Without this, the Remote Executor board will break! Also, any include must exist locally on the machine.

3. Bundled Asset Format (.e2z)

  • How it works: This format allows you to package your main E2 script, include-dependencies, and static assets (custom files) into a single compressed .zip archive. This is ideal for complex isolated programs that require external data or includes.

3. Bundled Asset Format (.e2z)

  • How it works: This format allows you to package your main E2 script, include-dependencies, and static assets (like custom text files) into a single compressed .zip archive. This is ideal for complex isolated programs that require external data.

  • Deployment Steps:

  1. Create a work folder on your real PC: garrysmod/data/e2files/testprog_e2z/.
  2. Inside it, create an internal folder named e2files.
  3. Save your main execution script (e.g. testprog_e2z.txt) inside testprog_e2z/e2files/ strictly under the name _main_.txt (resulting in testprog_e2z/e2files/_main_.txt).
  4. Copy the file includes/example_e2z.txt into the folder testprog_e2z/e2files/alx_pc/remote/includes (you will need to create alx_pc, alx_pc/remote and alx_pc/remote/includes subfolders).
  5. Create any static asset files (optional), such as testfile.txt with your custom content, directly in the root of your work folder (testprog_e2z/).
  6. Compress all files and folders from inside testprog_e2z/ into a single ZIP archive.
    • Crucial: The root of the zip archive must immediately contain your asset files (like testfile.txt) and the e2files folder. If you see the parent folder testprog_e2z inside the root of your ZIP archive, you did it wrong!
  7. Rename your compressed archive (e.g. testprog_e2z.zip) to testprog.zip.txt and place it into garrysmod/data/e2files/.
  8. Inside ALX OS, create a file named testprog.e2z and set its content to point to your archive: file://testprog.zip.txt.
  9. Ensure a Remote Executor board is installed in a PCI slot, then run the .e2z file.

Critical Note: Just like .e2p, you must add #include "alx_pc/remote/e2p_include" in your _main_.txt code. Assets are passed safely via the remote event payload. In .e2z you don't have to add e2p_include.txt into the archive, as it is loaded automatically by the Remote Executor.

Reference Template: There is an example e2z file on GitHub: example_e2z.zip.
You can check its structure and copy it to garrysmod/data/e2files/.
Then rename it to example_e2z.zip.txt and use as file://example_e2z.zip.txt when creating a file in ALX OS, or load it via HTTP using: https://raw.githubusercontent.com/AlexALX/wiremod_e2_os/refs/heads/master/examples/example_e2z.zip.

Reference Templates

You can check the example code and archive structures inside the repository:

Program Lifecycles Compared

Embedded (.e2e)

[ALX OS File] -> [Reads Function Name] -> [Triggers Core CPU] -> [Triggers Core GPU]

External (.e2r / .e2p / .e2z)

[ALX OS File] -> [Reads Source/Path/Archive] -> [PCI Card (Remote Executor)] -> [remoteupload to separate chip]

ALX PC

Development

Clone this wiki locally