Axon

README

✨ Axon: Visual Programming, For Real.

_{Yes, this logo is AI Generated, boo me, Im too poor to hire an artist}

Go from a visual idea to idiomatic, runnable Go code.
Axon is a visual, node-based programming language that bridges the gap between intuitive, flow-based logic and high-performance, real-world applications.

Features · Live Preview · Workflow · Getting Started · CLI Commands

---

🚀 What is Axon?

Tired of boilerplate? Teaching a new programmer? Want to see your logic?

Axon is your answer. Unlike toy block-based languages, Axon is designed for serious development. It provides a structured, visual environment to design complex systems, which it then transpiles directly into clean, human-readable, and performant Go code.

It’s the clarity of flowcharts with the power of a compiled language.

🎨 Official Visual Editor

To create and edit Axon graphs, use the official visual editor. It's a dedicated desktop application built with Wails and Svelte, providing a rich, interactive experience for building your visual programs.

The editor is developed in a separate repository:

➡️ github.com/Advik-B/Axon-Editor ⬅️

📺 Interactive Preview

The star of the show. Axon's previewer isn't just a static diagram. It's a living, breathing visualization of your graph's structure, complete with a spring-mass physics simulation and a live-transpiled code view.

https://github.com/user-attachments/assets/17ca4d01-5d11-417e-9d29-0c53ec3f2045

Pan, zoom, and drag nodes. The graph fluidly rearranges itself while showing the generated Go code in a side panel.
_{Yes the code for this is something I am not proud of. Yes. this is super jank. Yes it looks ugly}

✨ Core Features

• 🧠 Intuitive Node-Based Logic: Build programs by connecting nodes. Control execution flow (ExecEdge) and data flow (DataEdge) explicitly and visually.
• 🚀 Transpiles to Idiomatic Go: Generate clean, efficient, and readable Go code that you can compile and run anywhere. No black boxes.
• 🔍 Interactive Physics Preview: Launch a dynamic, physics-based visualization of your graph. Drag nodes, see connections spring into place, and get a feel for your program's structure.
• 💾 Git-Friendly Format: Graph files (.ax) are stored as human-readable JSON, making version control, diffing, and collaboration a breeze.
• 📦 Multiple File Formats: Choose the best format for your needs:
  • .ax: Human-readable JSON for editing and version control.
  • .axb: Raw Protobuf binary for fast loading.
  • .axd: Commented YAML for debugging.
  • .axc: Compressed binary for distribution.
• 🧩 Extensible by Design: Easily define custom nodes that map to your own Go functions or any function from the Go standard library.

---

🛠️ The Axon Workflow

Axon is built around a simple, powerful command-line interface.

1. Design: Create a .ax file

⚠️ Small note, in the (not too distant) future, I will create a proper node graph editor using Tauri

For now, I am sticking to writing the json files manually

The node graph preview is just some jank (spagetti) code I threw together

Define your logic in a simple JSON format. This example creates two constants, adds them, and prints the result.

add.ax

{
  "id": "basic-addition-v2",
  "name": "Add Numbers with Execution Flow",
  "imports": ["fmt"],
  "nodes": [
    { "id": "start", "type": "START" },
    { "id": "end", "type": "END" },
    { "id": "const1", "type": "CONSTANT", "label": "x", "outputs": [{ "type_name": "int" }], "config": { "value": "5" }},
    { "id": "const2", "type": "CONSTANT", "label": "y", "outputs": [{ "type_name": "int" }], "config": { "value": "3" }},
    { "id": "sum", "type": "OPERATOR", "label": "z", "inputs": [{ "name": "a", "type_name": "int" }, { "name": "b", "type_name": "int" }], "outputs": [{ "name": "out", "type_name": "int" }], "config": { "op": "+" }},
    { "id": "printer", "type": "FUNCTION", "label": "PrintResult", "impl_reference": "fmt.Println", "inputs": [{ "name": "a", "type_name": "int" }] }
  ],
  "data_edges": [
    { "from_node_id": "const1", "from_port": "out", "to_node_id": "sum", "to_port": "a" },
    { "from_node_id": "const2", "from_port": "out", "to_node_id": "sum", "to_port": "b" },
    { "from_node_id": "sum", "from_port": "out", "to_node_id": "printer", "to_port": "a" }
  ],
  "exec_edges": [
    { "from_node_id": "start", "to_node_id": "sum" },
    { "from_node_id": "sum", "to_node_id": "printer" },
    { "from_node_id": "printer", "to_node_id": "end" }
  ]
}

2. Visualize: Preview your graph

Before compiling, see your graph come to life!

axon preview examples/add.ax

3. Build: Transpile to Go

When you're ready, transpile your visual graph into a real Go program.

axon build examples/add.ax

This generates the following clean Go code in out/main.go:

package main

import (
	"fmt"
)

func main() {
	x := 5
	y := 3
	z := x + y
	fmt.Println(z)
}

4. Run: Execute your code

Run your new Go program just like any other.

go run out/main.go
# Output: 8

---

🚀 Getting Started

Prerequisites

• Go (version 1.24 or later)
• Make (for windows, refer to the chocolatey package)

Installation

1. Clone the repository:

   git clone https://github.com/Advik-B/Axon.git
   cd Axon
   

2. Install dependencies and tools: The Makefile simplifies installing the Go tools needed for development.

   make install-deps
   

3. Build the axon binary:

   make
   

4. Verify the installation: You should now have an axon (or axon.exe on Windows) executable.

   ./axon --help
   

🕹️ CLI Commands

Axon comes with a powerful and flexible set of tools:

Command	Description
axon build [file]	Transpiles any Axon graph (.ax, .axb, .axd, .axc) into a runnable out/main.go file.
axon preview [file]	Launches a beautiful, interactive, physics-based visualization of your graph.
axon pack [file]	Compresses any graph format into a highly efficient .axc binary archive using XZ compression.
axon unpack [file.axc]	Decompresses an .axc archive back into the standard .axb binary format.
axon convert <in-file> <out-file>	Converts between all Axon formats (.ax, .axd, .axb, .axc).

---

🗺️ Roadmap

• Core Transpiler: A fully working transpiler.
• Preview: A readonly visualiser for the graph
• Visual Editor: A full-fledged GUI for creating and editing .ax graphs from scratch.
• Live Reload: Automatically update the previewer when graph files change.
• Plugin Architecture: A formal way to extend Axon's core transpiler and previewer functionality.

---

📄 License

This project is licensed under the MIT License.

🫂Credits & Inspiration

Axon is heavily inspired by the elegance and power of Unreal Engine's Blueprints.