alchemist — Cursor Rules

This comprehensive document establishes a framework for developing robust, scalable systems in Rust 1.8+ that integrate Entity Component System patterns with Event-Driven Architecture, constrained by Domain-Driven Design principles, and utilizing NATS for exclusive message-based communication. The practices outlined here synthesize modern software architecture patterns to create highly decoupled, maintainable systems that leverage Rust's type safety and performance characteristics while maintaining clear domain boundaries and event-driven interactions.

Effective Rust development begins with proper module organization and consistent naming patterns. The module system in Rust serves three critical purposes: namespacing, scoping, and code organization[1]. When developing ECS-based systems, module structure becomes particularly important for maintaining clear separation between domain concepts, components, and systems. Variable and function naming should follow snake_case conventions consistently throughout the codebase[2]. This includes all function names, variable names, and module names. For example, movement_system, player_component, and health_value exemplify proper naming. Constants must use SCREAMING_SNAKE_CASE, such as MAX_ENTITIES or DEFAULT_HEALTH_VALUE[2]. Struct and trait names require PascalCase formatting, where each word begins with a capital letter without separators, such as HealthComponent, MovementSystem, or EventHandler[2]. Module organization should flatten public APIs to avoid redundant naming patterns[1]. Rather than exposing game::client::Client, the preferred approach exposes simply game::Client through strategic use of pub use declarations. This creates cleaner APIs while maintaining internal code organization. Private modules can use more descriptive internal structures without exposing implementation details to consumers. Scoping within modules provides fine-grained control over visibility. Use pub(crate) for items that should be accessible within the current crate but not exposed as public API[1]. The pub(super) visibility modifier restricts access to the parent module only, useful for internal implementation details that support public functionality without being part of the external interface.

Robust error handling forms the foundation of reliable ECS systems[1]. Define a centralized error module that flattens error types for clean client usage. Rather than forcing users to write game::error::Error, flatten the export to simply game::Error through module re-exports. This approach reduces verbosity while maintaining clear error semantics. Custom error types should implement appropriate traits based on their intended usage. For command-line applications or systems that need human-readable error output, implement the Display trait using derive macros for consistent formatting[1]. However, avoid defaulting to Display implementations for all error types, as this can create unnecessary complexity for purely internal errors. Error handling in ECS systems requires particular attention to component and system failure modes. Component operations may fail due to type mismatches, missing dependencies, or resource constraints. Systems must handle partial failures gracefully, allowing the overall simulation to continue when individual entities encounter errors. Define clear error boundaries that align with domain concepts rather than technical implementation details.

Constructor patterns in Rust ECS systems should balance simplicity with flexibility[1]. For simple types that can be constructed without arguments and cannot fail, implementing the Default trait provides the most idiomatic approach. This aligns with Rust ecosystem conventions and integrates seamlessly with existing libraries that expect Default implementations. More complex components may benefit from builder patterns, particularly when they require multiple optional parameters or complex initialization logic[1]. However, not every type that benefits from chainable setters requires a full builder implementation. Use builders judiciously for components with significant configuration complexity, while keeping simple components constructor-friendly. Component constructors should validate invariants at creation time when possible. This leverages Rust's type system to prevent invalid component states from propagating through the system. For example, a Health component might enforce positive values at construction time, eliminating the need for runtime validation in every system that processes health values.