forge/lib/models

Forge Models

This crate defines the shared data structures (models) used throughout the Forge application. These models represent the core entities of the game and are shared between the Extension, Service, and Repository layers.

Actor Model

The Actor struct represents a player in the game. It contains all persistent data associated with a character.

Fields

Field	Type	Description
uid	String	Unique Steam ID (64-bit). Immutable.
name	Option<String>	Player's display name.
loadout	serde_json::Value	JSON representation of the player's equipment.
position	Option<Vec<f64>>	[x, y, z] coordinates.
direction	f64	Compass direction (0-360).
stance	Option<String>	Player stance (e.g., "STAND", "CROUCH").
email	String	In-game email address (auto-generated).
phone_number	String	In-game phone number (auto-generated).
bank	f64	Money in the bank.
cash	f64	Money on hand.
earnings	f64	Total earnings.
state	String	Health/Status state (default: "HEALTHY").
holster	bool	Whether the weapon is holstered.
rank	Option<String>	Rank within an organization.
organization	String	ID of the organization the player belongs to.
transactions	Vec<serde_json::Value>	History of financial transactions.

Validation Rules

• UID: Must be a 17-digit numeric string.
• Name: Max 50 characters, cannot be empty if set.
• Position: Must be an array of 3 finite numbers.
• Direction: Must be between 0.0 and 360.0.
• Phone Number: Must start with "0160" and be 10 digits long.
• Email: Must end with "@spearnet.mil".

Arma Integration

The Actor struct implements FromArma and IntoArma for seamless conversion between Rust structs and SQF values.

• From Arma: Expects a JSON string.
• To Arma: Returns a JSON string.

Organization Model

The Org struct represents a guild, clan, or group of players.

Fields

Field	Type	Description
id	String	Unique identifier (slug).
owner	String	UID of the organization leader.
name	String	Display name of the organization.
funds	f64	Shared organization funds.
reputation	i64	Organization's reputation score.

Validation Rules

• ID: Alphanumeric and underscores only. Cannot be empty.
• Owner: Must be a valid 17-digit UID.
• Name: Max 100 characters, no control characters.
• Funds: Cannot be negative.

Contributing

We welcome contributions to the Forge Models crate! When adding a new model, please follow these guidelines to ensure consistency.

Adding a New Model

To add a new model (e.g., Vehicle), follow these steps:

1. Define the Struct: Create a new file in src/ (e.g., src/vehicle.rs) and define your struct.

   • Derive Debug, Clone, Serialize, and Deserialize.
   • Use #[serde(default)] for optional fields that should have default values.

   #[derive(Debug, Clone, Serialize, Deserialize)]
   pub struct Vehicle {
       pub id: String,
       pub class_name: String,
       #[serde(default)]
       pub damage: f64,
   }
   

2. Implement new: Provide a constructor that initializes the struct with valid defaults.

   impl Vehicle {
       pub fn new(id: String, class_name: String) -> Result<Self, String> {
           let vehicle = Self {
               id,
               class_name,
               damage: 0.0,
           };
           vehicle.validate()?;
           Ok(vehicle)
       }
   }
   

3. Implement validate: Create a method to enforce business rules and data integrity.

   impl Vehicle {
       pub fn validate(&self) -> Result<(), String> {
           if self.id.is_empty() {
               return Err("ID cannot be empty".to_string());
           }
           if self.damage < 0.0 || self.damage > 1.0 {
               return Err("Damage must be between 0.0 and 1.0".to_string());
           }
           Ok(())
       }
   }
   

4. Implement Arma Traits: Implement FromArma and IntoArma for SQF interoperability.

   use arma_rs::{FromArma, IntoArma, Value};
   
   impl FromArma for Vehicle {
       fn from_arma(s: String) -> Result<Self, arma_rs::FromArmaError> {
           serde_json::from_str(&s).map_err(|e| ... )
       }
   }
   
   impl IntoArma for Vehicle {
       fn to_arma(&self) -> Value {
           let json = serde_json::to_string(self).unwrap_or_default();
           Value::String(json)
       }
   }
   

5. Register the Module: Add your new module to src/lib.rs.

   pub mod vehicle;
   pub use vehicle::Vehicle;