Skip to content

Commit a54d857

Browse files
NetroScriptNetroScript
committed
Add README and license
1 parent c5c9edb commit a54d857

File tree

3 files changed

+298
-0
lines changed

3 files changed

+298
-0
lines changed

‎Cargo.toml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22
name = "godot-mcap"
33
version = "0.1.0"
44
edition = "2024"
5+
license = "MIT"
56

67
[dependencies]
78
godot = { version = "0.3.5", features = ["api-4-3", "register-docs"] }

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2025 NetroScript (and contributors)
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 276 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,276 @@
1+
# godot-mcap — MCAP reader/writer for Godot 4
2+
3+
This project adds MCAP bindings to GDScript using a native GDExtension written in Rust.
4+
5+
> MCAP is an open source container file format for multimodal log data. It supports multiple channels of timestamped pre-serialized data, and is ideal for use in pub/sub or robotics applications. ~ [mcap.dev](https://mcap.dev)
6+
7+
It lets you:
8+
- Write MCAP files from GDScript
9+
- Read MCAP files (stream or indexed) and access channels, schemas, metadata, and attachments
10+
- Iterate messages efficiently (with seeking and channel/time filters)
11+
- Replay messages in real-time with a dedicated Node
12+
13+
This extension is built with godot-rust and targets Godot >=4.3 APIs.
14+
15+
16+
## Features
17+
18+
- Writer
19+
- Add schemas, channels, attachments, metadata
20+
- Write full messages or header+payload to known channels
21+
- Chunking and compression (Zstd and/or LZ4 when enabled at build time)
22+
- Reader
23+
- Direct message streaming without indexes
24+
- Indexed queries when a Summary is present (time windows, per-channel, counts)
25+
- Attachments and metadata access via summary indexes
26+
- Zero-copy mmap when possible, otherwise fallback to the FileAccess API (so supports reading files from `res://` and `user://`)
27+
- Iterator and replay
28+
- `MCAPMessageIterator` for efficient for-in iteration with seeks and filters
29+
- `MCAPReplay` Node to emit messages over time (idle or physics), with speed/looping
30+
- Godot-friendly Resources for common MCAP types (Channel, Schema, Message, Attachment, Metadata)
31+
- Error handling via `get_last_error()` on reader/writer
32+
33+
34+
## Installation
35+
36+
Automatic releases tbd.
37+
38+
## Building from source
39+
40+
Prerequisites
41+
- Godot >=4.3 (matching the `api-4-3` bindings used here)
42+
- Rust toolchain (stable)
43+
44+
Build the native library
45+
46+
```fish
47+
cargo build --release
48+
```
49+
50+
Artifacts (Linux)
51+
- Debug: `target/debug/libgodot_mcap.so`
52+
- Release: `target/release/libgodot_mcap.so`
53+
54+
55+
### Godot project setup (GDExtension)
56+
57+
1) Copy the built library into your project, e.g.
58+
- `res://bin/linux_x86_64/libgodot_mcap.so`
59+
60+
2) Create a `res://godot-mcap.gdextension` file pointing to the library:
61+
62+
```ini
63+
[configuration]
64+
entry_symbol = "gdext_rust_init"
65+
compatibility_minimum = 4.3
66+
reloadable = true
67+
68+
[libraries]
69+
linux.x86_64 = "res://bin/linux_x86_64/libgodot_mcap.so"
70+
```
71+
72+
3) Open the project in Godot. You should see classes like `MCAPWriter`, `MCAPReader`, and `MCAPReplay` in the Create dialog (Script/Node) and documentation available in the editor.
73+
74+
Notes
75+
- The `entry_symbol` string is provided by godot-rust and should remain `gdext_rust_init`.
76+
- On other platforms, add matching `libraries` entries with the correct paths and filenames for your target (Windows: `.dll`, macOS: `.dylib`).
77+
78+
79+
## Quickstart
80+
81+
All timestamps are microseconds (usec) by default. They are using the engine time since startup. However you are free to also use any other time scheme.
82+
83+
### Write an MCAP file (GDScript)
84+
85+
```gdscript
86+
var w := MCAPWriter.new()
87+
88+
# Optional: configure options before open
89+
w.options = MCAPWriteOptions.new()
90+
w.options.compression = MCAPWriteOptions.MCAP_COMPRESSION_ZSTD # or LZ4/None depending on build features
91+
92+
if not w.open("user://out.mcap"):
93+
push_error("open failed: %s" % w.get_last_error())
94+
return
95+
96+
# Optional schema
97+
var schema_id := w.add_schema("MyType", "jsonschema", PackedByteArray())
98+
99+
# Channel
100+
var ch_id := w.add_channel(schema_id, "/topic", "json", {})
101+
102+
# Write via known channel (header + payload)
103+
var hdr := MCAPMessageHeader.create(ch_id)
104+
hdr.sequence = 1
105+
var payload := PackedByteArray("{\"hello\":\"world\"}".to_utf8_buffer())
106+
if not w.write_to_known_channel(hdr, payload):
107+
push_error("write failed: %s" % w.get_last_error())
108+
109+
# Or write a full message with an embedded channel
110+
var ch := MCAPChannel.create("/alt")
111+
ch.message_encoding = "json"
112+
var msg := MCAPMessage.create(ch, payload)
113+
w.write(msg)
114+
115+
# Optional: attachments & metadata
116+
# var att := MCAPAttachment.create("snapshot.bin", "application/octet-stream", PackedByteArray())
117+
# w.attach(att)
118+
# var meta := MCAPMetadata.create("run_info", {"key": "value"})
119+
# w.write_metadata(meta)
120+
121+
w.flush() # finish current chunk and flush I/O
122+
if not w.close():
123+
push_error("close failed: %s" % w.get_last_error())
124+
```
125+
126+
127+
### Read messages (GDScript)
128+
129+
```gdscript
130+
var reader := MCAPReader.open("user://out.mcap", false)
131+
132+
# Stream all messages (no summary required)
133+
for msg in reader.messages():
134+
print(msg.channel.topic, " @ ", msg.log_time)
135+
136+
# Indexed helpers (require summary)
137+
if reader.has_summary():
138+
var it := reader.stream_messages_iterator()
139+
it.seek_to_time(1_000_000) # 1s
140+
for msg in it:
141+
print("iter: ", msg.channel.topic, " @ ", msg.log_time)
142+
143+
var window := reader.messages_in_time_range(2_000_000, 3_000_000)
144+
print("msgs in window: ", window.size())
145+
146+
var atts := reader.attachments()
147+
var metas := reader.metadata_entries()
148+
149+
if reader.get_last_error() != "":
150+
push_error(reader.get_last_error())
151+
```
152+
153+
154+
### Replay in real-time (Node)
155+
156+
```gdscript
157+
var reader := MCAPReader.open("user://out.mcap", false)
158+
var replay := MCAPReplay.new()
159+
add_child(replay)
160+
replay.set_reader(reader)
161+
replay.set_time_range(-1, -1) # full file
162+
replay.speed = 1.0
163+
replay.looping = false
164+
replay.processing_mode = MCAPReplay.PROCESSING_MODE_IDLE
165+
replay.message.connect(_on_replay_message)
166+
var ok := replay.start()
167+
if not ok:
168+
push_error("MCAPReplay failed to start: missing summary or no data")
169+
170+
func _on_replay_message(msg: MCAPMessage) -> void:
171+
# Handle per-message payload
172+
print(msg.channel.topic, msg.log_time)
173+
```
174+
175+
176+
## API highlights
177+
178+
Writer: `MCAPWriter` (RefCounted)
179+
- `open(path: String) -> bool`
180+
- `add_schema(name: String, encoding: String, data: PackedByteArray) -> int`
181+
- `add_channel(schema_id: int, topic: String, message_encoding: String, metadata: Dictionary) -> int`
182+
- `write(message: MCAPMessage) -> bool`
183+
- `write_to_known_channel(header: MCAPMessageHeader, data: PackedByteArray) -> bool`
184+
- `write_private_record(opcode: int, data: PackedByteArray, include_in_chunks: bool) -> bool`
185+
- `attach(attachment: MCAPAttachment) -> bool`
186+
- `write_metadata(meta: MCAPMetadata) -> bool`
187+
- `flush() -> bool`, `close() -> bool`, `get_last_error() -> String`
188+
189+
Reader: `MCAPReader` (factory methods, no public `new()`)
190+
- `open(path: String, ignore_end_magic: bool) -> MCAPReader`
191+
- `from_bytes(data: PackedByteArray, ignore_end_magic: bool) -> MCAPReader`
192+
- `messages() -> Array[MCAPMessage]`, `raw_messages() -> Array[Dictionary]`
193+
- `stream_messages_iterator() -> MCAPMessageIterator`
194+
- `attachments() -> Array[MCAPAttachment]`, `metadata_entries() -> Array[MCAPMetadata]`
195+
- Indexed helpers: `messages_in_time_range`, `messages_for_channel`, `messages_for_channels`, `messages_for_topic`
196+
- Info: `first_message_time_usec`, `last_message_time_usec`, `duration_usec`, `channel_ids`, `topic_names`, `topic_to_channel_id`, `channels_for_schema`, `schema_for_channel`
197+
- Counts: `message_count_total`, `message_count_for_channel`, `message_count_in_range`, `message_count_for_channel_in_range`
198+
- `read_summary() -> MCAPSummary?`, `has_summary() -> bool`, `get_last_error() -> String`
199+
200+
Iterator: `MCAPMessageIterator` (RefCounted)
201+
- Godot iterator protocol: usable directly in `for` loops
202+
- `for_channel(id)`, `seek_to_time(t)`, `seek_to_time_nearest(t)`, `seek_to_next_on_channel(id, after_t)`
203+
- `get_message_at_time(id, t)`, `peek_message()`, `get_next_message()`, `has_next_message()`
204+
205+
Replay: `MCAPReplay` (Node)
206+
- Properties: `speed: float`, `looping: bool`, `processing_mode: ProcessingMode`
207+
- Methods: `set_reader()`, `set_filter_channels()`, `set_time_range()`, `start()`, `stop()`, `seek_to_time()`
208+
- Signals: `message(MCAPMessage)`
209+
210+
Types (Resources)
211+
- `MCAPWriteOptions`, `MCAPCompression`
212+
- `MCAPSchema`, `MCAPChannel`, `MCAPMessage`, `MCAPMessageHeader`, `MCAPAttachment`, `MCAPMetadata`
213+
- Summary/index wrappers: `MCAPSummary`, `MCAPFooter`, `MCAPChunkIndex`, `MCAPMessageIndexEntry`, `MCAPAttachmentIndex`, `MCAPMetadataIndex`
214+
215+
216+
## Compression features
217+
218+
By default, both `zstd` and `lz4` features are enabled and passed through to the underlying `mcap` crate.
219+
220+
- Disable all compression:
221+
222+
```fish
223+
cargo build --no-default-features
224+
```
225+
226+
- Enable only LZ4:
227+
228+
```fish
229+
cargo build --no-default-features --features lz4
230+
```
231+
232+
- Enable only Zstd:
233+
234+
```fish
235+
cargo build --no-default-features --features zstd
236+
```
237+
238+
At runtime, choose the compression via `MCAPWriteOptions.compression`.
239+
240+
241+
## Tips and troubleshooting
242+
243+
- Library fails to load in Godot
244+
- Ensure `entry_symbol = "gdext_rust_init"` and your `libraries` paths are correct per-platform
245+
- Build type must match the copied file (Debug vs Release) and your CPU/OS
246+
- Godot 4.3 is required for the `api-4-3` bindings used by this build
247+
- Reading partial files
248+
- Use `MCAPReader.open(path, true)` to `ignore_end_magic` for truncated/incomplete captures
249+
- Performance
250+
- When a Summary exists, prefer `stream_messages_iterator()` or the indexed helpers for large files
251+
- `flush()` on the writer ends the current chunk to make in-progress files streamable
252+
253+
254+
## Development
255+
256+
- Build: `cargo build` or `cargo build --release`
257+
- Lints/tests: at the moment there are no Rust tests bundled; contributions welcome
258+
- Target Godot API: 4.3 (see `Cargo.toml` dependency features for `godot = { features = ["api-4-3"] }`)
259+
260+
261+
## Maybe planned
262+
263+
- Publish binary releases for common platforms
264+
- Add a `demo/` Godot project with example scenes and scripts
265+
- CI for building and packaging per-platform artifacts
266+
267+
268+
## Acknowledgements
269+
270+
- [mcap (Rust)](https://crates.io/crates/mcap)
271+
- [godot-rust](https://github.com/godot-rust/gdext)
272+
273+
274+
## License
275+
276+
The code of this repository is licensed under the MIT License (see `LICENSE`).

0 commit comments

Comments
 (0)