https://github.com/portwatcher/vue-godot
bridging Vue.js and Godot Engine for game UI and cross platform applications
https://github.com/portwatcher/vue-godot
electron flutter godot javascript lynx react-native tauri typescript vue
Last synced: 3 months ago
JSON representation
bridging Vue.js and Godot Engine for game UI and cross platform applications
- Host: GitHub
- URL: https://github.com/portwatcher/vue-godot
- Owner: portwatcher
- Created: 2025-02-20T06:00:20.000Z (over 1 year ago)
- Default Branch: develop
- Last Pushed: 2026-02-25T10:29:57.000Z (4 months ago)
- Last Synced: 2026-02-25T11:33:13.669Z (4 months ago)
- Topics: electron, flutter, godot, javascript, lynx, react-native, tauri, typescript, vue
- Language: TypeScript
- Homepage:
- Size: 4.28 MB
- Stars: 33
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Vue Godot
A small simple project that bridges Vue.js and Godot.
This project is for:
- Write game UI using Vue.js
- Write cross platform applications using Vue.js with Godot as the runtime
This project is far from production ready. follow me on [@juryxiong](https://x.com/juryxiong) for updates.
```vue
// Test.vue
import { ref } from 'vue'
const count = ref(1)
const handleClick = () => {
count.value = count.value + 1
}
```
```ts
// main.ts
import { createApp } from '@vue-godot/runtime-tscn'
import { Control } from 'godot'
import Test from './Test.vue'
export default class App extends Control {
_ready() {
const app = createApp(Test)
app.mount(this)
}
}
```
## How It Works
vue-godot is a custom Vue renderer that targets Godot's scene tree instead of the DOM. The key pieces:
- **`@vue-godot/runtime-tscn`** — A Vue custom renderer (`createRenderer` from `@vue/runtime-core`) that maps Vue operations to Godot node tree operations: `createElement` → `ClassDB.instantiate()`, `insert` → `add_child()`, `patchProp` → `el.set()` / signal `connect()`, etc.
- **`@vue-godot/cli`** — A CLI tool (`vue-godot`) for vue-godot projects. Currently supports generating Vue `GlobalComponents` type augmentation from GodotJS typings so Volar provides autocomplete and type checking for Godot nodes in Vue templates.
- **Vite** builds the Vue app as a CJS library (`dist/app.js`), with `godot` as an external. The Godot scene (`.tscn`) attaches this script to a `Control` node.
- In the **Godot editor**, GodotJS runs `dist/app.js`. The `_ready()` method calls `createApp(Root).mount(this)`, and Vue takes over the subtree.
Upper-cased tags in templates (e.g. ``, ``) are treated as custom elements and resolved at runtime via `ClassDB.instantiate(tag)`.
## Repository Structure
```
vue-godot/
├── packages/
│ ├── runtime-tscn/ # Vue custom renderer for Godot
│ └── cli/ # CLI tool: vue-godot gen-types, scaffolding, etc.
├── apps/
│ ├── v-model/ # Example: two-way binding with TextEdit
│ ├── v-on/ # Example: event handling with @pressed
│ └── template-ref/ # Example: template refs
└── turbo.json # Turborepo config
```
Each app has the following layout:
```
apps//
├── project.godot # Godot project file
├── app.tscn # Main scene — attaches dist/app.js to a Control node
├── typings/ # GodotJS-generated type declarations (godot*.gen.d.ts)
│ └── godot.vue-components.gen.d.ts # Generated by @vue-godot/cli
├── vue/
│ ├── vite.config.ts # Vite config — builds vue/src/main.ts → dist/app.js
│ ├── tsconfig.json # Vue/Volar tsconfig (separate from Godot root tsconfig)
│ └── src/
│ ├── main.ts # Entry: createApp(Root).mount(this)
│ ├── *.vue # Vue SFC components
│ └── env.d.ts # *.vue module declaration for TypeScript
├── tsconfig.json # Godot root tsconfig (excludes vue/)
├── dist/ # Build output (loaded by Godot at runtime)
└── package.json
```
## Getting Started
### Prerequisites
- **Node.js** >= 18
- **GodotJS editor** — download from https://github.com/ialex32x/GodotJS-Build/releases
> **Note:** GodotJS 1.0.0-2 has a scene codegen bug where `SceneTSDCodeGen.make_path` doesn't strip `res://` from scene paths, producing `ERROR: Could not create directory: './typings/res:/'`. This was fixed on the [main branch](https://github.com/godotjs/GodotJS/blob/main/scripts/jsb.editor/src/jsb.editor.codegen.ts) (method renamed to `make_scene_path` with `res://` stripping) but no Godot 4.4 build includes the fix yet. The errors are harmless and don't affect runtime. To suppress them, go to **Editor → Editor Settings → search `GodotJS`** and set `codegen/generate_scene_dts` to `false`.
### Install & Build
```bash
npm install
npm run build # builds all packages + apps via Turborepo
```
### Run an example
Open the GodotJS editor and open any app's `project.godot`, for example `apps/v-on/project.godot`. Press **F5** to run the scene.
## Development Workflow
### 1. Open the Godot project
Open one of the example apps (e.g. `apps/v-model/project.godot`) in the GodotJS editor. On first open, GodotJS auto-generates TypeScript declarations for all engine classes into the `typings/` directory (`godot0.gen.d.ts` … `godot8.gen.d.ts`, `godot.mix.d.ts`, etc.).
### 2. Generate Vue component types
```bash
cd apps/v-model
npm run gen:types
```
This runs `vue-godot gen-types`, which reads the Godot typings and produces `typings/godot.vue-components.gen.d.ts` — a `GlobalComponents` augmentation that gives Volar full autocomplete and type checking for Godot node tags in `.vue` templates.
Re-run this whenever Godot typings are regenerated (e.g. after a Godot version upgrade).
### 3. Write Vue components
Edit `.vue` files under `vue/src/`. Use Godot node class names as tags directly in templates:
```vue
import { ref } from 'vue'
const text = ref('')
```
- **Props** map to Godot node properties (`:text`, `:visible`, `:size`, etc.)
- **Events** map to Godot signals (`@pressed`, `@text_changed`, etc. via `v-on`)
- All standard Vue features work: `ref()`, `computed()`, `watch()`, `v-if`, `v-for`, template refs, etc.
### 4. Write the entry point
`vue/src/main.ts` is the entry point. It creates a Vue app and mounts it onto a Godot `Control` node:
```ts
import { createApp } from '@vue-godot/runtime-tscn'
import { Control } from 'godot'
import Test from './Test.vue'
export default class App extends Control {
_ready() {
const app = createApp(Test)
app.mount(this)
}
}
```
This class is attached to a `Control` node in the Godot scene (`.tscn` file).
### 5. Build
```bash
npm run build # from repo root — builds everything
# or
cd apps/v-model && npm run build # build a single app
```
Vite compiles `vue/src/main.ts` into `dist/app.js` (CJS format, `godot` external). The Godot scene references this file.
### 6. Run in Godot
Press **F5** in the GodotJS editor. Godot loads `dist/app.js`, the `_ready()` method fires, and Vue renders its component tree into the Godot scene.
### Iteration loop
```
Edit .vue / .ts → npm run build → F5 in Godot → see changes
```
## Creating a New App
1. Copy an existing app directory (e.g. `apps/v-model`) to `apps/`
2. Update `package.json` name field
3. Update `project.godot` project name
4. Open `apps//project.godot` in the GodotJS editor to generate fresh typings
5. Run `npm run gen:types` to generate Vue component types
6. Edit `vue/src/` with your components
7. `npm run build` and press **F5** in Godot
## Packages
| Package | Description |
| ------------------------- | ---------------------------------------------------- |
| `@vue-godot/runtime-tscn` | Vue custom renderer for Godot scene tree |
| `@vue-godot/html` | HTML-like Vue components built on Godot nodes |
| `@vue-godot/cli` | CLI tool for vue-godot projects |
### `@vue-godot/cli`
```bash
vue-godot [options]
```
#### `create` / `integrate`
Both `create` (new project) and `integrate` (existing Godot project) accept a `--html` flag that configures `@vue-godot/html` automatically — setting up the Vite compiler config and plugin registration so lowercase HTML tags (`
`, `![]()
`, etc.) work as Godot-backed components with zero renaming.
```bash
vue-godot create my-app --html
vue-godot integrate --html
```
#### `gen-types`
Generate Vue `GlobalComponents` type augmentation from GodotJS typings.
```bash
vue-godot gen-types [--typings ] [--out ] [--ancestor ] [--vue-src ]
```
| Option | Default | Description |
| ------------ | ----------------------------------------- | ------------------------------------------------ |
| `--typings` | `./typings` | Directory containing `godot*.gen.d.ts` files |
| `--out` | `/godot.vue-components.gen.d.ts` | Output file path |
| `--ancestor` | `Control` | Base class — only descendants are included |
| `--vue-src` | `./vue/src` | Vue source dir — generates `env.d.ts` shim there |