wip

docs/CREATING_NEW_OBJECTS.md

@@ -0,0 +1,232 @@
+# Guide: Creating New OSIRIS Objects
+
+This guide explains how to properly create new object types in OSIRIS that integrate with the Rhai scripting engine and context storage.
+
+## Step-by-Step Process
+
+### 1. Create the Object Module
+
+Create a new file in the appropriate directory under `src/objects/`:
+- `src/objects/legal/` for legal objects
+- `src/objects/money/` for financial objects
+- `src/objects/heroledger/` for HeroLedger objects
+- etc.
+
+### 2. Define the Object Struct
+
+**CRITICAL**: The struct MUST derive `crate::DeriveObject` to automatically implement the `Object` trait.
+
+```rust
+use crate::store::BaseData;
+use serde::{Deserialize, Serialize};
+
+/// Your object description
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, crate::DeriveObject)]
+pub struct YourObject {
+    /// Base data for object storage (REQUIRED)
+    pub base_data: BaseData,
+    
+    /// Your custom fields
+    pub title: String,
+    pub status: YourStatus,
+    // ... other fields
+}
+```
+
+**Required traits:**
+- `Debug` - for debugging
+- `Clone` - required by Object trait
+- `Serialize, Deserialize` - for JSON serialization
+- `PartialEq` - for comparisons
+- `crate::DeriveObject` - **CRITICAL** - auto-implements Object trait
+
+**Required field:**
+- `base_data: BaseData` - MUST be present for object storage
+
+### 3. Implement Constructor and Methods
+
+```rust
+impl YourObject {
+    /// Create a new object
+    pub fn new(id: u32) -> Self {
+        let base_data = BaseData::with_id(id, String::new());
+        Self {
+            base_data,
+            title: String::new(),
+            status: YourStatus::default(),
+            // ... initialize other fields
+        }
+    }
+    
+    /// Fluent builder methods
+    pub fn title(mut self, title: impl ToString) -> Self {
+        self.title = title.to_string();
+        self
+    }
+    
+    // ... other methods
+}
+```
+
+### 4. Create Rhai Bindings Module
+
+Create `rhai.rs` in the same directory:
+
+```rust
+use ::rhai::plugin::*;
+use ::rhai::{CustomType, Dynamic, Engine, EvalAltResult, Module, TypeBuilder};
+
+use super::{YourObject, YourStatus};
+
+/// Register your modules with the Rhai engine
+pub fn register_your_modules(parent_module: &mut Module) {
+    // Register custom types
+    parent_module.set_custom_type::<YourObject>("YourObject");
+    parent_module.set_custom_type::<YourStatus>("YourStatus");
+    
+    // Merge functions
+    let your_module = exported_module!(rhai_your_module);
+    parent_module.merge(&your_module);
+}
+
+#[export_module]
+mod rhai_your_module {
+    use super::YourObject;
+    use ::rhai::EvalAltResult;
+    
+    // Constructor
+    #[rhai_fn(name = "new_your_object", return_raw)]
+    pub fn new_your_object(id: i64) -> Result<YourObject, Box<EvalAltResult>> {
+        Ok(YourObject::new(id as u32))
+    }
+    
+    // Builder methods
+    #[rhai_fn(name = "title", return_raw)]
+    pub fn set_title(
+        obj: YourObject,
+        title: String,
+    ) -> Result<YourObject, Box<EvalAltResult>> {
+        Ok(obj.title(title))
+    }
+    
+    // Getters
+    #[rhai_fn(name = "title", pure)]
+    pub fn get_title(obj: &mut YourObject) -> String {
+        obj.title.clone()
+    }
+}
+
+// CustomType implementations
+impl CustomType for YourObject {
+    fn build(mut builder: TypeBuilder<Self>) {
+        builder.with_name("YourObject");
+    }
+}
+
+impl CustomType for YourStatus {
+    fn build(mut builder: TypeBuilder<Self>) {
+        builder.with_name("YourStatus");
+    }
+}
+```
+
+### 5. Update Module Exports
+
+In `mod.rs` of your object category:
+
+```rust
+pub mod your_object;
+pub mod rhai;
+
+pub use your_object::{YourObject, YourStatus};
+pub use rhai::register_your_modules;
+```
+
+In `src/objects/mod.rs`:
+
+```rust
+pub mod your_category;
+
+pub use your_category::{YourObject, YourStatus};
+```
+
+### 6. Register in Engine (CRITICAL STEP)
+
+In `src/engine.rs`, add the save registration in the `OsirisPackage` definition:
+
+```rust
+def_package! {
+    pub OsirisPackage(module) : StandardPackage {
+        // ... existing registrations ...
+        
+        // Add your object's save method
+        FuncRegistration::new("save")
+            .set_into_module(module, |ctx: &mut OsirisContext, obj: crate::objects::YourObject| ctx.save_object(obj));
+        
+        // ... existing registrations ...
+        
+        // Register your modules
+        register_your_modules(module);
+    }
+}
+```
+
+Also add the import at the top of `engine.rs`:
+
+```rust
+use crate::objects::your_category::rhai::register_your_modules;
+```
+
+### 7. Create Example Script
+
+Create `examples/engine/XX_your_object.rhai`:
+
+```rhai
+print("=== Your Object Example ===\n");
+
+// Get context
+let ctx = get_context(["alice", "bob"]);
+
+// Create object
+let obj = new_your_object(1)
+    .title("Example Title");
+
+print("Object created: " + obj.title());
+
+// Store in context
+ctx.save(obj);
+print("Object stored");
+
+print("\n=== Example Complete ===");
+```
+
+## Checklist
+
+Before considering your object complete, verify:
+
+- [ ] Struct derives `crate::DeriveObject`
+- [ ] Struct has `base_data: BaseData` field
+- [ ] Rhai module created with `register_*_modules` function
+- [ ] Custom types registered with `set_custom_type`
+- [ ] Module exported in `mod.rs` files
+- [ ] Save method registered in `src/engine.rs`
+- [ ] Module registration added to `OsirisPackage` in `src/engine.rs`
+- [ ] Example script created and tested
+- [ ] Example runs successfully with `cargo run --example engine examples/engine/XX_your_object.rhai`
+
+## Common Mistakes to Avoid
+
+1. **Forgetting `crate::DeriveObject`** - Without this, the Object trait won't be implemented
+2. **Missing `base_data` field** - Required for all storable objects
+3. **Not registering save in engine.rs** - The save method MUST be in engine.rs, not context.rs
+4. **Not calling `set_custom_type`** - Rhai won't recognize your type
+5. **Not merging the exported module** - Your functions won't be available
+
+## Example: Contract Object
+
+See the Contract object implementation as a reference:
+- Struct: `src/objects/legal/contract.rs`
+- Rhai bindings: `src/objects/legal/rhai.rs`
+- Module exports: `src/objects/legal/mod.rs` and `src/objects/mod.rs`
+- Engine registration: `src/engine.rs` (line ~110 and ~138)
+- Example: `examples/engine/12_contract.rhai`