Best Practices

Follow these best practices to get the most out of Basilisk.

BDL Definition Best Practices

Follow naming conventions: Use PascalCase for entities, camelCase for variables, and UPPER_SNAKE_CASE for enum values
Use entity inheritance: Create base entities for common fields and extend them for specific use cases
Define clear primary keys: Always specify primary keys explicitly, even if using shorthand
Use optional fields wisely: Mark fields as optional only when they truly may not be present
Provide default values: Use defaults for fields that have sensible fallback values
Document with comments: Add comments to explain complex structures or business logic
Validate references: Use references to maintain data integrity between related entities

Keep spreadsheets organized: Use clear column headers that match your BDL variable names
Validate data before building: Check for missing required fields, invalid references, and type mismatches
Use consistent formatting: Ensure dates, numbers, and enums follow consistent formats
Document data sources: Add notes or comments in spreadsheets to explain data decisions
Backup important data: The system creates backups automatically, but keep your own backups for critical changes

Use environment patterns: Follow common patterns like Dev → QA → Staging → Production
Enable safety features in production: Always enable forced diff review and safety checks for production environments
Test in lower environments first: Always test builds in development or QA before production
Assign definitions to environments: Lock environments to specific definitions to prevent incompatible builds
Document environment purposes: Clearly document what each environment is used for

Use descriptive build IDs: Follow naming conventions or use meaningful identifiers
Add detailed descriptions: Document what each build contains and why it was created
Review build logs: Always check execution logs and warnings before publishing
Compare builds before publishing: Use the comparison feature to understand changes
Keep build history: Don't delete old builds; they serve as a history and can be used for rollback
Monitor build times: Track build performance and optimize if builds take too long

Establish cadences: Define clear release cadences (weekly, monthly, etc.) for regular content updates
Plan content ahead: Prepare content in advance to meet cadence deadlines
Use version control: Track changes to definitions and understand the evolution of your data structures
Coordinate with game systems: Ensure data builds align with game system requirements and integration points
Test thoroughly: Test new content in isolated environments before releasing to players
Monitor after deployment: Watch for issues after publishing and be ready to rollback if needed

Fix errors immediately: Address build errors before attempting to publish
Understand error messages: Read error logs carefully to identify root causes
Validate definitions: Ensure definitions are valid before using them for builds
Check data types: Verify that spreadsheet data matches the expected types in your definition
Verify references: Ensure all references point to valid entities
Test edge cases: Test with empty data, missing optional fields, and boundary values

Limit production access: Restrict who can publish to production environments
Use environment locks: Enable safety features to prevent accidental deployments
Review changes carefully: Always review diffs before publishing, especially in production
Audit build history: Regularly review who created builds and when
Protect credentials: Keep Google Platform credentials secure and rotate them regularly

Optimize data structures: Design entities and indexes for efficient lookups
Minimize bundle size: Group related data into bundles but avoid overly large bundles
Use indexes effectively: Create indexes for frequently accessed lookups
Monitor build performance: Track build times and optimize slow builds
Cache appropriately: In your application, cache data builds appropriately based on update frequency