GridPlacement 6.0 (formerly GridBuilding)
Development ⚠️ GridPlacement 6.0 documentation is in active development. APIs and content may change, and the site may be temporarily unstable.

External Integration Guide

Overview

This guide covers the enhanced Placeable/PlaceableSequence architecture with external system compatibility, TOML/JSON support, and database-friendly data structures.

Architecture Score: 9.5/10

The enhanced POCS architecture provides excellent external integration capabilities with clean separation of concerns and robust data structures.

Key Features

1. External System Compatibility

The architecture supports integration with:

  • Generic item/inventory frameworks
  • External data sources (JSON, TOML, APIs)
  • Database systems (SQLite, PostgreSQL, MySQL, MongoDB)
  • Third-party systems via adapter pattern

2. Data Structure Enhancements

PlaceableDefinition now includes:

  • ExternalReferences - Links to external systems
  • Tags - For filtering and categorization
  • CreatedAt/UpdatedAt - Database-friendly timestamps
  • Version - Migration support
  • Properties - Extensible custom properties

3. Serialization Support

  • JSON: Full serialization with JsonHelper integration
  • TOML: Configuration-friendly format
  • External Sources: Load from files, APIs, databases

Implementation Guide

Setting Up External Integration

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

// Create integration manager
var integrationManager = new PlaceableIntegrationManager();

// Register inventory system
var adapter = InventorySystemFactory.CreateAdapter("default");
integrationManager.RegisterInventorySystem("default", adapter.Value);

// Register data provider
var provider = new ExternalDataProvider();
integrationManager.RegisterDataProvider("external_api", provider);

Creating Placeables with External References

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

var placeable = new PlaceableDefinition
{
    Id = "advanced_building",
    Name = "Advanced Building",
    Category = PlaceableCategory.Building,
    Tags = new List<string> { "military", "advanced", "tier3" },
    ExternalReferences = new ExternalReferenceCollection()
};

// Add external system reference
placeable.ExternalReferences.AddOrUpdateReference(new ExternalPlaceableReference
{
    ExternalId = "building_001",
    SystemName = "mod_system",
    SystemVersion = "2.1",
    MappingData = new Dictionary<string, object>
    {
        ["mod_category"] = "military_structure",
        ["required_tech"] = "advanced_construction"
    }
});

Working with Sequences

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

var sequence = new PlaceableSequence
{
    Id = "base_construction",
    Name = "Base Construction Sequence",
    Category = SequenceCategory.Building,
    RequiredInventoryItems = new List<string> { "construction_kit" }
};

sequence.Steps.Add(new SequenceStep
{
    Id = "foundation",
    PlaceableId = "foundation_block",
    RelativePosition = new Vector2I(0, 0),
    Order = 0,
    ExternalDependencies = new List<string> { "survey_complete" }
});

Inventory System Integration

Supported Inventory Types

  1. Default: Basic inventory with 64 stack size
  2. Inventory V2: Enhanced with metadata and rarity
  3. Advanced: Full-featured with weight and attributes
  4. Mod: Mod-specific integration

Custom Inventory Adapter

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

public class CustomInventoryAdapter : IPlaceableInventoryAdapter
{
    public Result<object> CreateInventoryItem(PlaceableDefinition placeable)
    {
        var item = new
        {
            id = placeable.Id,
            name = placeable.Name,
            custom_properties = ConvertToCustomFormat(placeable)
        };
        return Result<object>.Success(item);
    }

    public Result<bool> ValidateCompatibility(PlaceableDefinition placeable, string inventoryType)
    {
        // Custom validation logic
        return Result<bool>.Success(true);
    }
}

Database Integration

Schema Generation

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

// Generate SQLite schema
var sqliteSchema = DatabaseSchemaGenerator.GenerateSchema("sqlite", new SchemaOptions
{
    IncludeExternalReferences = true,
    IncludeTags = true
});

// Generate PostgreSQL schema
var postgresSchema = DatabaseSchemaGenerator.GenerateSchema("postgresql");

// Generate migration
var migration = DatabaseSchemaGenerator.GenerateMigration("postgresql", 1, 2);

Database Compatibility

The architecture supports:

  • SQLite: Lightweight, file-based storage
  • PostgreSQL: Full-featured with JSONB support
  • MySQL: Compatible with JSON columns
  • MongoDB: Document-oriented storage

External Data Loading

From JSON Files

1
2

var loader = new ExternalDataLoader();
var placeable = loader.LoadFromSource("placeables.json", "json");

From TOML Files

1

var placeable = loader.LoadFromSource("placeables.toml", "toml");

From Collections

1

var collection = loader.LoadCollectionFromSource("all_placeables.json");

Configuration

Placeable Configuration

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

{
  "placeables": {
    "advanced_building": {
      "id": "advanced_building",
      "name": "Advanced Building",
      "category": "Building",
      "external_sources": [
        {
          "name": "mod_system",
          "location": "mods/military/data.json",
          "type": "file",
          "format": "json"
        }
      ],
      "inventory_mappings": {
        "default": "advanced_building_item",
        "inventory_v2": "mil_structure_001"
      }
    }
  }
}

Database Configuration

1
2
3
4
5
6
7
8
9

{
  "database_config": {
    "database_type": "postgresql",
    "connection_string": "host=localhost;database=gridbuilding",
    "table_name": "placeables",
    "auto_create_schema": true,
    "indexed_columns": ["id", "category", "created_at"]
  }
}

Testing

Running Integration Tests

1
2
3

var tests = new ExternalIntegrationFrameworkTests();
var result = tests.RunAllTests();
Console.WriteLine($"Tests {(result ? "passed" : "failed")}");

Test Coverage

  • External system compatibility
  • Inventory system integration
  • Database schema generation
  • Serialization/deserialization
  • Performance benchmarks
  • Cross-system compatibility

Performance Considerations

Caching

External data is cached by default to improve performance:

1
2
3
4
5

var config = new ExternalIntegrationConfig
{
    CacheExternalData = true,
    CacheDurationMinutes = 30
};

Batch Operations

Use batch operations for better performance:

1
2
3

// Load multiple sources
var sources = new[] { "file1.json", "file2.toml", "file3.json" };
var collection = loader.LoadFromMultipleSources(sources);

Lazy Loading

External references are loaded on-demand to minimize startup time.

Migration Guide

From v5.0 to v6.0

  1. Update PlaceableDefinition: Add new external integration properties
  2. Migrate External References: Use migration scripts
  3. Update Inventory Systems: Register new adapters
  4. Generate Database Schemas: Use schema generator

Migration Scripts

1
2
3
4
5
6
7
8

-- Add external references column
ALTER TABLE placeables ADD COLUMN external_references JSONB;

-- Add tags column
ALTER TABLE placeables ADD COLUMN tags TEXT[];

-- Add version column
ALTER TABLE placeables ADD COLUMN version INTEGER NOT NULL DEFAULT 1;

Best Practices

1. External References

  • Keep external references minimal for performance
  • Use meaningful system names
  • Version your external mappings
  • Handle external system failures gracefully

2. Database Design

  • Use appropriate data types for your database
  • Create indexes on frequently queried columns
  • Consider partitioning for large datasets
  • Regularly backup external mapping data

3. Inventory Integration

  • Validate compatibility before conversion
  • Handle inventory system limitations
  • Use appropriate stack sizes and item types
  • Consider inventory system-specific features

4. Serialization

  • Choose JSON for complex nested data
  • Use TOML for configuration files
  • Validate external data before loading
  • Handle serialization errors gracefully

Troubleshooting

Common Issues

  1. External System Not Available

    • Check system registration
    • Verify network connectivity
    • Validate system configuration

  2. Database Compatibility Issues

    • Verify database type support
    • Check schema compatibility
    • Run migration scripts

  3. Inventory Conversion Failures

    • Validate placeable data
    • Check inventory adapter compatibility
    • Review inventory system requirements

Debug Information

Enable debug logging for troubleshooting:

1
2
3
4
5
6

var config = new ExternalIntegrationConfig
{
    Enabled = true,
    TimeoutMs = 10000,
    RetryAttempts = 3
};

Future Enhancements

Planned Features

  1. GraphQL Support: For complex external data queries
  2. Event-Driven Integration: Real-time external system updates
  3. Advanced Caching: Multi-layer caching strategies
  4. Performance Monitoring: Built-in metrics and analytics
  5. Automated Testing: Continuous integration test suites

Extension Points

The architecture is designed for extensibility:

  • Custom inventory adapters
  • External data providers
  • Database persistence adapters
  • Serialization formats
  • Validation rules

Conclusion

The enhanced Placeable/PlaceableSequence architecture provides robust external integration capabilities while maintaining clean separation of concerns and excellent performance characteristics. The modular design allows for easy extension and customization to meet specific integration requirements.