📝 Issue Title: Create Models Fundamentals Documentation File
🔍 Scope
Extract and reorganize the foundational concepts from the existing models.md file to create a focused fundamentals guide. This file should serve as the entry point for developers new to Dojo models and ECS architecture.
This will be part of the models documentation restructuring under /getting-started/basics/models/models-fundamentals.md.
🔄 How to Implement the Issue
Documentation Structure:
Step 1: Create /client/pages/getting-started/basics/models/ModelsFundamentals.md
Step 2: Extract and reorganize content from lines 1-200 and 300-400 of existing models.md
Step 3: Structure content for progressive learning from basic to intermediate concepts
Step 4: Ensure gaming-focused examples throughout
Content Requirements:
Section 1: Introduction to Models and ECS (from lines 1-50)
- What are models in Dojo Engine
- ECS pattern explanation (Entity-Component-System)
- Why models matter for onchain games
- Relationship between entities, components (models), and systems
- Gaming-specific benefits of the ECS approach
Section 2: Basic Model Anatomy (from lines 51-150)
#[dojo::model] attribute explanation- Simple model structure with single key
- Basic field types (u8, u16, u32, felt252, ContractAddress)
- Essential derives: Drop, Serde, Copy, Debug, PartialEq
- First simple example: Player model with basic stats
Section 3: Keys and Entity Identification (from lines 150-250)
#[key] attribute and its purpose- Single key vs composite key patterns
- Key ordering requirements
- Querying models with different key structures
- Entity identification in ECS context
Section 4: Field Types and Metadata (from lines 51-200 scattered)
- Cairo primitive types in models
- When to use each type (u8 vs u32 vs felt252)
- Required derives and their purposes
- Optional derives and when to use them
- Type safety considerations for game data
Section 5: Custom Types Implementation (from lines 300-400)
- Implementing custom types in models
- Introspect trait requirements
- Automatic derivation vs manual implementation
- IntrospectPacked for space efficiency
- Custom enums and structs in game models
Specific Content to Extract:
Player Model Example (preserve from original):
#[derive(Copy, Drop, Serde, Debug, PartialEq)]
#[dojo::model]
pubstructPlayer {
#[key]
pubaddress:ContractAddress,
pubcurrent_beast_id:u16,
pubbattles_won:u16,
pubbattles_lost:u16,
publast_active_day:u32,
pubcreation_day:u32,
}Beast Model with Composite Keys (preserve from original):
#[derive(Copy, Drop, Serde, Debug, PartialEq)]
#[dojo::model]
pubstructBeast {
#[key]
pubplayer:ContractAddress,
#[key]
pubbeast_id:u16,
publevel:u8,
pubexperience:u16,
pubbeast_type:BeastType,
}Custom Type Examples (preserve from original):
- Potion model with custom Rarity enum
- Stats struct implementation
- Introspect manual implementation example
Content Guidelines:
Target Length: ~200-250 lines
Learning Progression: Basic concepts → Intermediate patterns
Gaming Focus: All examples should use gaming terminology and concepts
Self-Contained: File should be readable without requiring other model files
Cross-References: Link to models-patterns.md for advanced usage
✅ Acceptance Criteria
Foundation Knowledge:
Complete explanation of what models are and their role in ECS
Clear understanding of basic model structure and syntax
Comprehensive coverage of key concepts and field types
Practical examples using gaming scenarios
Content Organization:
Logical flow from ECS introduction to custom types
Each section builds on previous concepts
Code examples are practical and gaming-focused
Cross-references guide readers to next learning steps
Learning Experience:
New developers can understand models after reading this file
Content serves as foundation for more advanced model topics
Examples are realistic and applicable to game development
File can be consumed independently or as part of larger learning path
Code Quality:
All code examples are tested and functional
Examples use consistent gaming terminology
Code follows Dojo best practices and conventions
Examples demonstrate both simple and composite key patterns
📸 Additional Context
Source Content Location:
- Lines 1-50: ECS introduction and model overview
- Lines 51-200: Model anatomy, keys, and basic structure
- Lines 300-400: Custom types and Introspect implementation
Target Audience:
- Developers new to Dojo Engine
- Game developers new to ECS architecture
- Blockchain developers learning onchain game development
Learning Objectives:
After reading this file, developers should understand:
- What models represent in game architecture
- How to define basic model structures
- How to use keys for entity identification
- How to implement custom types in models
Success Criteria:
- Serves as comprehensive introduction to Dojo models
- Enables developers to create their first game models
- Provides foundation for learning advanced model patterns
- Reduces confusion about ECS concepts in gaming context
📋 Implementation Guidelines
Content Extraction:
Extract relevant sections from existing models.md file
Reorganize content for better learning flow
Preserve all gaming-focused examples and terminology
Ensure code examples remain functional after extraction
Writing Style:
Maintain gaming-focused explanations throughout
Use progressive disclosure (simple to complex)
Include practical examples for each concept
Provide clear explanations of why each concept matters
File Organization:
Use clear section headers for easy navigation
Include table of contents for longer sections
Add appropriate cross-references to related concepts
End with next steps pointing to models-patterns.md
Contribution Guidelines:
Please ensure you read and follow the contribution guidelines in the project's [README](/README.md) file
Extract content from existing models.md rather than rewriting from scratch
Test all code examples to ensure they remain functional
Maintain the gaming focus and terminology throughout
Follow established documentation formatting standards
📝 Issue Title: Create Models Fundamentals Documentation File
🔍 Scope
Extract and reorganize the foundational concepts from the existing models.md file to create a focused fundamentals guide. This file should serve as the entry point for developers new to Dojo models and ECS architecture.
This will be part of the models documentation restructuring under /getting-started/basics/models/models-fundamentals.md.
🔄 How to Implement the Issue
Documentation Structure:
Step 1: Create /client/pages/getting-started/basics/models/ModelsFundamentals.md
Step 2: Extract and reorganize content from lines 1-200 and 300-400 of existing models.md
Step 3: Structure content for progressive learning from basic to intermediate concepts
Step 4: Ensure gaming-focused examples throughout
Content Requirements:
Section 1: Introduction to Models and ECS (from lines 1-50)
Section 2: Basic Model Anatomy (from lines 51-150)
#[dojo::model]attribute explanationSection 3: Keys and Entity Identification (from lines 150-250)
#[key]attribute and its purposeSection 4: Field Types and Metadata (from lines 51-200 scattered)
Section 5: Custom Types Implementation (from lines 300-400)
Specific Content to Extract:
Player Model Example (preserve from original):
Beast Model with Composite Keys (preserve from original):
Custom Type Examples (preserve from original):
Content Guidelines:
Target Length: ~200-250 lines
Learning Progression: Basic concepts → Intermediate patterns
Gaming Focus: All examples should use gaming terminology and concepts
Self-Contained: File should be readable without requiring other model files
Cross-References: Link to models-patterns.md for advanced usage
✅ Acceptance Criteria
Foundation Knowledge:
Complete explanation of what models are and their role in ECS
Clear understanding of basic model structure and syntax
Comprehensive coverage of key concepts and field types
Practical examples using gaming scenarios
Content Organization:
Logical flow from ECS introduction to custom types
Each section builds on previous concepts
Code examples are practical and gaming-focused
Cross-references guide readers to next learning steps
Learning Experience:
New developers can understand models after reading this file
Content serves as foundation for more advanced model topics
Examples are realistic and applicable to game development
File can be consumed independently or as part of larger learning path
Code Quality:
All code examples are tested and functional
Examples use consistent gaming terminology
Code follows Dojo best practices and conventions
Examples demonstrate both simple and composite key patterns
📸 Additional Context
Source Content Location:
Target Audience:
Learning Objectives:
After reading this file, developers should understand:
Success Criteria:
📋 Implementation Guidelines
Content Extraction:
Extract relevant sections from existing models.md file
Reorganize content for better learning flow
Preserve all gaming-focused examples and terminology
Ensure code examples remain functional after extraction
Writing Style:
Maintain gaming-focused explanations throughout
Use progressive disclosure (simple to complex)
Include practical examples for each concept
Provide clear explanations of why each concept matters
File Organization:
Use clear section headers for easy navigation
Include table of contents for longer sections
Add appropriate cross-references to related concepts
End with next steps pointing to models-patterns.md
Contribution Guidelines:
Please ensure you read and follow the contribution guidelines in the project's [README](/README.md) file
Extract content from existing models.md rather than rewriting from scratch
Test all code examples to ensure they remain functional
Maintain the gaming focus and terminology throughout
Follow established documentation formatting standards