https://github.com/dsh0416/godot-cef
A cross-platform GPU-accelerated CEF-based (Chromium Embedded Framework) WebView Extension for Godot 4
https://github.com/dsh0416/godot-cef
cef chromium d3d12 gdextension godot godot4 metal offscreen-rendering vulkan webview
Last synced: 23 days ago
JSON representation
A cross-platform GPU-accelerated CEF-based (Chromium Embedded Framework) WebView Extension for Godot 4
- Host: GitHub
- URL: https://github.com/dsh0416/godot-cef
- Owner: dsh0416
- License: mit
- Created: 2025-12-31T12:25:54.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2026-05-22T19:50:18.000Z (25 days ago)
- Last Synced: 2026-05-22T21:37:10.553Z (25 days ago)
- Topics: cef, chromium, d3d12, gdextension, godot, godot4, metal, offscreen-rendering, vulkan, webview
- Language: Rust
- Homepage: https://godotcef.org/
- Size: 3.58 MB
- Stars: 168
- Watchers: 2
- Forks: 16
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
# Godot CEF
A high-performance Chromium Embedded Framework (CEF) integration for Godot Engine 4.5+, written in Rust. Render web content directly inside your Godot games and applications with full support for modern web standards, JavaScript, HTML5, and CSS3.
[](https://github.com/dsh0416/godot-cef/actions/workflows/build.yml)
[](https://github.com/dsh0416/godot-cef/actions/workflows/test.yml)
[](https://github.com/dsh0416/godot-cef/releases)
[](https://godotengine.org/asset-library/asset/4694)
[](https://github.com/dsh0416/godot-cef/issues)
[](https://github.com/dsh0416/godot-cef/pulls)
## Features
- **Web Rendering in Godot** — Display any web content as a texture using the `CefTexture` node (extends `TextureRect`)
- **Accelerated Off-Screen Rendering** — GPU-accelerated rendering using platform-native graphics APIs for maximum performance
- **Software Rendering Fallback** — Automatic fallback to CPU-based rendering when accelerated rendering is unavailable
- **Dynamic Scaling** — Automatic handling of DPI changes and window resizing
- **Multi-Process Architecture** — Proper CEF subprocess handling for stability and consistency
- **Remote Debugging** — Built-in Chrome DevTools support
- **Typed IPC (CBOR)** — Send/receive typed primitives, arrays, and binary buffers (`Variant` / JS values) without manual JSON serialization
- **Listener-based JS Bridge** — Multi-subscriber IPC listeners via `addListener/removeListener/hasListener`
- **No-Panic Runtime Policy** — Panics in crate runtime code are treated as bugs and blocked by lint/CI policy
## Screenshots
| | |
|:---:|:---:|
|  |  |
| GitHub page rendered with full interactivity | Web content integrated into 3D scenes |
|  |  |
| WebGPU demos running natively | WebGL Aquarium at ~120 FPS with 10,000 fish |
## Quick Start
### Installation
Download the latest pre-built binaries from the [Releases](https://github.com/dsh0416/godot-cef/releases) page, extract the addon to your Godot project's `addons/` folder, and you're ready to go!
> [!NOTE]
> During export/package builds, Godot may convert some imported assets into other formats. If your frontend is built with Vite and needs specific source files to remain as-is, you can use [`vite-plugin-godot-keep-import`](https://github.com/LemonNekoGH/vite-plugin-keep-import-for-godot) to keep imports for selected file types.
### Basic Usage
```gdscript
extends Control
func _ready():
var cef_texture = CefTexture.new()
cef_texture.url = "https://example.com"
cef_texture.enable_accelerated_osr = true # Enable GPU acceleration
add_child(cef_texture)
```
### Example with Signals
```gdscript
extends Node2D
@onready var browser = $CefTexture
func _ready():
# Set initial URL
browser.url = "https://example.com"
# Connect to signals
browser.load_finished.connect(_on_page_loaded)
browser.ipc_message.connect(_on_message_received)
func _on_page_loaded(url: String, status: int):
print("Page loaded: ", url)
# Execute JavaScript
browser.eval("document.body.style.backgroundColor = '#f0f0f0'")
func _on_message_received(message: String):
print("Received from web: ", message)
```
## Documentation
For comprehensive API documentation, examples, and guides, visit the [full documentation](https://godotcef.org/).
| Resource | Description |
|----------|-------------|
| [**API Reference**](https://godotcef.org/api/) | Complete CefTexture API documentation |
| [**Properties**](https://godotcef.org/api/properties.html) | Node properties and configuration |
| [**Methods**](https://godotcef.org/api/methods.html) | Browser control and JavaScript execution |
| [**Signals**](https://godotcef.org/api/signals.html) | Events and notifications |
| [**IME Support**](https://godotcef.org/api/ime-support.html) | International text input |
## Platform Support
| Platform | DirectX 12 | Metal | Vulkan | Software Rendering |
|----------|------------|-------|--------|-------------------|
| **Windows** | ✅ (Note 1) | n.a. | ✅ (Note 2) | ✅ |
| **macOS** | n.a. | ✅ | ❌ [[#4]](https://github.com/dsh0416/godot-cef/issues/4) | ✅ |
| **Linux** | n.a. | n.a. | ✅ (Note 2) | ✅ |
Platform Notes
1. **Windows DirectX 12**: Requires at least Godot 4.6 beta 2. Godot 4.5.1 contains a bug where `RenderingDevice.get_driver_resource` on DirectX 12 textures always returns 0.
2. **Vulkan Backends**: See [#4](https://github.com/dsh0416/godot-cef/issues/4) for details. On Windows and Linux, we use hooking to inject extensions for GPU-accelerated rendering (x86_64 only). This is a workaround until [godotengine/godot-proposals#13969](https://github.com/godotengine/godot-proposals/issues/13969) is resolved. On Linux with NVIDIA proprietary drivers, DMA-BUF acceleration requires the `nvidia-drm.modeset=1` kernel parameter; see the [Vulkan support guide](https://godotcef.org/api/vulkan-support.html#linux-nvidia-driver-requirement) for GRUB setup steps.
3. **Software Rendering**: On platforms where accelerated rendering is not yet implemented, the extension automatically falls back to software rendering using CPU-based frame buffers.
## Limitations
### Media Codec Support
The prebuilt CEF binaries do not include proprietary codecs (H.264, AAC, MP3) due to licensing restrictions in the Chromium/CEF stack. This is an upstream limitation that cannot be addressed within this project.
| Codec Type | Supported (Royalty-Free) | Not Supported (Proprietary) |
|------------|--------------------------|----------------------------|
| **Video** | VP8, VP9, AV1, Theora | H.264/AVC, H.265/HEVC |
| **Audio** | Opus, Vorbis, FLAC, WAV, PCM | MP3, AAC |
| **Container** | WebM, Ogg, WAV | MP4 (with H.264/AAC) |
Using Royalty-Free Alternatives
For best compatibility, encode your media using these royalty-free formats:
**Recommended for video:** WebM container with VP9 or AV1 video and Opus audio
```bash
# Convert video to WebM (VP9 + Opus)
ffmpeg -i input.mp4 -c:v libvpx-vp9 -crf 30 -b:v 0 -c:a libopus -b:a 128k output.webm
# Convert video to WebM (AV1 + Opus) - better compression, slower encoding
ffmpeg -i input.mp4 -c:v libaom-av1 -crf 30 -c:a libopus -b:a 128k output.webm
```
**Recommended for audio:** Opus in WebM/Ogg container
```bash
# Convert audio to Opus
ffmpeg -i input.mp3 -c:a libopus -b:a 128k output.ogg
```
These formats offer comparable or better quality than proprietary alternatives and work out of the box.
Building CEF with Proprietary Codecs (Advanced)
If you require H.264/AAC/MP3 support, you must build CEF from source with proprietary codec flags enabled:
```
proprietary_codecs=true
ffmpeg_branding=Chrome
```
**Important considerations:**
- Building CEF requires ~100GB disk space and several hours
- H.264 licensing may apply depending on distribution scale
- FFmpeg licensing terms (LGPL/GPL) must be followed
- You assume responsibility for codec licensing compliance
See the [CEF build documentation](https://bitbucket.org/chromiumembedded/cef/wiki/BranchesAndBuilding) for detailed instructions.
## Building from Source
For detailed build instructions, see [CONTRIBUTING.md](CONTRIBUTING.md#development-setup).
### Quick Build Steps
1. **Install prerequisites**: [mise](https://mise.jdx.dev/) and Godot 4.5+
2. **Install the project toolchain**:
```bash
mise trust
mise install
```
The commands below assume mise shell integration is active. If your shell is not configured for mise activation yet, prefix commands with `mise exec --`.
3. **Install CEF binaries**:
```bash
export CEF_PATH="$HOME/.local/share/cef"
export-cef-dir --version "$CEF_VERSION" --force "$CEF_PATH"
```
`CEF_VERSION` is pinned in `mise.toml` to the CEF runtime build version from the resolved `cef` / `cef-dll-sys` crate in `Cargo.lock`. For example, crate version `148.1.0+147.0.14` uses CEF runtime `147.0.14`.
4. **Build**:
```bash
cargo xtask bundle --release
```
5. **Copy to Godot project**: Copy built artifacts from `target/release/` to your project's `addons/godot_cef/bin//` folder.
See the `addons/godot_cef/godot_cef.gdextension` file for the complete list of required files per platform.
### Validate Packaged Addon
You can validate bundled addon artifacts with:
```bash
cargo xtask validate --addon addons/godot_cef
```
## No-Panic Policy
This project treats panics in crate runtime code as bugs. We do not use panic-based control flow.
- Workspace lint policy denies `panic!`, `unwrap()`, `expect()`, `todo!()`, and `unimplemented!()`.
- `cargo clippy --workspace --all-targets -- -D warnings` is used as a CI gate.
- Release builds use `panic = "abort"` to prevent unwind-based panic behavior in production artifacts.
If you find a runtime panic path, please open an issue or submit a fix.
## Comparison with Similar Projects
| Feature | **Godot CEF** (this project) | [godot_wry](https://github.com/doceazedo/godot_wry) | [gdcef](https://github.com/Lecrapouille/gdcef) |
|---------|------------------------------|-----------------------------------------------------|------------------------------------------------|
| **Browser Engine** | Chromium (CEF) | Native OS webview (WRY) | Chromium (CEF) |
| **Implementation** | Rust | Rust | C++ |
| **Rendering** | Texture (OSR) | Window overlay | Texture (OSR) |
| **GPU Acceleration** | ✅ Yes | ✅ Yes | ❌ Software only |
| **3D Scene Support** | ✅ Yes | ❌ No (always on top) | ✅ Yes |
| **HiDPI Aware** | ✅ Yes | ✅ Yes | ❌ No |
| **Consistent Cross-Platform** | ✅ Same engine everywhere | ❌ Different engines | ✅ Same engine everywhere |
| **JS ↔ GDScript IPC** | ✅ Yes | ✅ Yes | ✅ Yes |
| **Godot Filesystem Access** | ✅ Yes (`res://`) | ✅ Yes | ❌ No |
| **Project Export** | ✅ Yes | ✅ Yes | ❌ No |
| **Headless CI Support** | ✅ Yes | ❌ No | ✅ Yes |
| **Bundle Size** | Large (~100MB+) | Small (uses OS webview) | Large (~100MB+) |
When to Use Each
**Choose Godot CEF (this project) if you need:**
- GPU-accelerated web rendering for high performance
- Smooth and high performance interactive UI
- Web content as a texture in 3D scenes (e.g., in-game screens, VR/AR interfaces)
- Consistent behavior across all platforms (same Chromium engine everywhere)
- Modern Rust codebase with godot-rust
**Choose godot_wry if you need:**
- Minimal bundle size (uses the OS's built-in webview)
- Simple overlay UI that doesn't need to be part of the 3D scene
- Lightweight integration without bundling a full browser
**Choose gdcef if you need:**
- C++ codebase for a more mature CEF integration with more docs
- Proven, mature implementation with longer history
### Motivation
This project was created during development of [Engram](https://store.steampowered.com/app/3928930/_Engram/). While our first demo version benefited greatly from an interactive UI written in Vue.js using godot_wry, we encountered limitations with the wry-based approach. Since other implementations have long struggled with GPU-accelerated OSR, we decided to create our own solution.
## Contributing
We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on:
- Setting up your development environment
- Code style and testing requirements
- Pull request process
- Reporting issues
## License
MIT License — Copyright 2025-2026 Delton Ding
See [LICENSE](LICENSE) for details.
## Related Repositories
- [custom-unit-pxp](https://github.com/LemonNekoGH/custom-unit-pxp): A set of packages for the custom `pxp` unit (`px` + `var`) that can be useful for game UI workflows.
## Acknowledgments
- [godot_wry](https://github.com/doceazedo/godot_wry)
- [gdcef](https://github.com/Lecrapouille/gdcef)
- [CEF (Chromium Embedded Framework)](https://bitbucket.org/chromiumembedded/cef)
- [godot-rust](https://github.com/godot-rust/gdext)
- [cef-rs](https://github.com/tauri-apps/cef-rs)
## Star History
