Clarify documentation considering resource comparisions

Author: NetroScript

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "godot-mcap"
-version = "0.1.0"
+version = "0.1.1"
 edition = "2024"
 license = "MIT"
 

Cargo.toml

@@ -202,7 +202,7 @@ func _on_replay_message(msg: MCAPMessage) -> void:
 ```
 
 
-## API highlights
+## API Overview
 
 Writer: `MCAPWriter` (RefCounted)
 - `open(path: String) -> bool`
@@ -243,6 +243,22 @@ Types (Resources)
 - Summary/index wrappers: `MCAPSummary`, `MCAPFooter`, `MCAPChunkIndex`, `MCAPMessageIndexEntry`, `MCAPAttachmentIndex`, `MCAPMetadataIndex`
 
 
+### Object identity and equality
+
+When reading, this extension constructs new Godot Resource instances every time:
+
+- Each call to `MCAPReader.messages()`, `raw_messages()`, `attachments()`, `metadata_entries()`, or when iterating via `MCAPMessageIterator`, creates new `MCAPMessage`, `MCAPChannel`, `MCAPSchema`, `MCAPAttachment`, and `MCAPMetadata` objects.
+- The same logical channel or schema may therefore be represented by different Resource instances across calls. Do not compare objects by identity/reference.
+
+Compare by stable properties instead:
+
+- Channels: compare `channel.id` (preferred) or `channel.topic`.
+- Schemas: compare `schema.id` (preferred), optionally with `schema.name`/`schema.encoding`.
+- Messages: compare `message.channel.id` together with `message.sequence` or `message.log_time`.
+- Attachments: compare a tuple such as `(name, log_time)` or use offsets if you maintain them externally.
+- Metadata: compare `name` (and/or specific keys in `metadata`).
+
+
 ## Compression features
 
 By default, both `zstd` and `lz4` features are enabled and passed through to the underlying `mcap` crate.

README.md

@@ -14,6 +14,8 @@ use std::collections::HashSet;
 /// - Iterates messages in log-time order across chunks and channels.
 /// - Supports optional per-channel filtering and multiple seek helpers.
 /// - Requires a Summary section in the file.
+/// - Identity note: messages and their nested channel/schema are newly constructed per iteration step.
+///   Compare by fields (e.g. `msg.channel.id`, `msg.sequence`, `msg.log_time`) rather than by object identity.
 ///
 /// Usage (GDScript)
 /// ```gdscript

src/reader/iterator.rs

@@ -22,6 +22,8 @@ use std::sync::Arc;
 /// - Loads an MCAP file into memory for fast random access and optional indexed queries.
 /// - Provides direct streaming of messages (`messages`, `raw_messages`) and an indexed iterator (`stream_messages_iterator`).
 /// - Exposes attachment and metadata access via summary indexes when present.
+/// - Identity note: every read constructs new Godot Resources (`MCAPMessage`, `MCAPChannel`, `MCAPSchema`, etc.).
+///   Do not rely on instance equality across calls; compare by stable fields instead (e.g. `channel.id`, `schema.id`).
 ///
 /// Memory & I/O
 /// - When opening from a path, the reader first tries to memory-map (mmap) the file for zero-copy random access.

src/reader/mcap_reader.rs

@@ -5,5 +5,7 @@ mod mcap_reader;
 mod replay;
 
 pub use iterator::MCAPMessageIterator;
+#[allow(unused_imports)]
 pub use mcap_reader::MCAPReader;
+#[allow(unused_imports)]
 pub use replay::{MCAPReplay, ProcessingMode};

src/reader/mod.rs

@@ -216,7 +216,7 @@ impl MCAPReplay {
             Some(r) => r.clone(),
             None => return false,
         };
-        // Build a fresh iterator from reader
+        // Build a new iterator from reader
         let mut it = reader.bind().stream_messages_iterator();
         // Fast-path single-channel filter
         if let Some(set) = &self.filter_channels {

src/reader/replay.rs

@@ -159,7 +159,11 @@ pub struct MCAPSummary {
     pub metadata_indexes: Array<Gd<MCAPMetadataIndex>>,
 }
 
-/// Describes a schema used by one or more [MCAPChannel]s in an MCAP file
+/// Describes a schema used by one or more [MCAPChannel]s in an MCAP file.
+///
+/// Identity note: Instances returned by the reader are newly constructed on
+/// each call/iteration. Do not compare by object identity/reference; prefer
+/// comparing by stable fields such as `id` (and optionally `name`/`encoding`).
 #[derive(GodotClass)]
 #[class(no_init, base=Resource)]
 pub struct MCAPSchema {
@@ -177,7 +181,11 @@ pub struct MCAPSchema {
     pub data: PackedByteArray,
 }
 
-/// Describes a channel which [Message]s are published to in an MCAP file
+/// Describes a channel which [Message]s are published to in an MCAP file.
+///
+/// Identity note: Reader methods and iterators construct new `MCAPChannel`
+/// instances as needed. Compare channels by `id` (preferred) or by `topic`,
+/// not by object identity.
 #[derive(GodotClass)]
 #[class(no_init, base=Resource)]
 pub struct MCAPChannel {
@@ -198,7 +206,12 @@ pub struct MCAPChannel {
     pub metadata: Dictionary,
 }
 
-/// An event in an MCAP file, published to a [MCAPChannel]
+/// An event in an MCAP file, published to a [MCAPChannel].
+///
+/// Identity note: The embedded `channel` Resource is newly constructed and may
+/// be a distinct instance from channels returned by other reads/iterations.
+/// Compare messages by fields like `channel.id` together with `sequence` or
+/// `log_time`, rather than by object identity.
 #[derive(GodotClass)]
 #[class(no_init, base=Resource)]
 pub struct MCAPMessage {
@@ -219,7 +232,11 @@ pub struct MCAPMessage {
     pub data: PackedByteArray,
 }
 
-/// An attachment and its metadata in an MCAP file
+/// An attachment and its metadata in an MCAP file.
+///
+/// Identity note: Attachments returned by the reader are newly constructed.
+/// For equality, prefer comparing by content properties such as `(name, log_time)`
+/// or your own external keys, rather than by object identity.
 #[derive(GodotClass)]
 #[class(no_init, base=Resource)]
 pub struct MCAPAttachment {
@@ -258,7 +275,11 @@ pub struct MCAPMessageHeader {
     pub publish_time: i64,
 }
 
-/// MCAP Metadata record
+/// MCAP Metadata record.
+///
+/// Identity note: Metadata objects are newly constructed on each read. For
+/// equality, compare by `name` (and relevant `metadata` keys) rather than by
+/// object identity.
 #[derive(GodotClass)]
 #[class(no_init, base=Resource)]
 pub struct MCAPMetadata {