Grid Placement

GridBuilding Plugin Workspace

This VS Code workspace provides a focused development environment for the GridBuilding plugin with access to all necessary tools and documentation.

Workspace Structure

The workspace includes the following folders:

  • GridBuilding Plugin - Main plugin source code
  • Toolkits - Analysis and development tools (../../../toolkits)
  • Scripts - Build and validation scripts (../../../../scripts)
  • GridBuilding Docs - Hugo documentation site (../../../../docs/gridplacement)
  • Legacy GDScript Plugin (grid_building) - Original GDScript toolkit and tests (../../tools/grid_building)

Quick Start

1
2
3

# Demo + GDScript health bundle (scan + smoke/full)
./scripts/testing/demo_doctor.sh --help
./scripts/testing/demo_doctor.sh all

Opening the Workspace

  1. Open VS Code
  2. File → Open Workspace
  3. Navigate to and select GridBuilding.code-workspace

Essential Commands

Building

  • Ctrl+Shift+B - Build main solution
  • F1 → Tasks: Run Task → build-isolation - Build isolation tests only

Testing

  • F1 → Tasks: Run Task → test-all - Run all tests
  • F1 → Tasks: Run Task → test-isolation - Run isolation tests only

Code Analysis

  • F1 → Tasks: Run Task → run-toolkit-analysis - Run static analysis
  • F1 → Tasks: Run Task → validate-structure - Validate project structure

Documentation

  • F1 → Tasks: Run Task → build-docs - Build GridBuilding documentation

Debugging Configurations

Launch Configurations

  • Launch Godot (GridBuilding) - Launch Godot with the GridBuilding plugin
  • Debug GridBuilding Tests - Debug main test suite
  • Debug Isolation Tests - Debug PlaceablePOCSLoading isolation tests

Test Development Workflow

  1. Make changes to isolation tests in Tests/Working/PlaceablePOCSLoading/
  2. Run test-isolation task for quick feedback
  3. Run test-all task to verify integration
  4. Use debug configurations for step-through debugging

Key Features

Integrated Tooling

  • Static Analysis: Code smell detection and quality checks
  • Structure Validation: Automated project structure verification
  • Documentation: Direct access to Hugo docs building
  • Test Isolation: Focused test development environment
  • C# Dev Kit - Enhanced C# development experience
  • Godot Tools - Godot engine integration
  • Rust Analyzer - For toolkit development
  • YAML - For configuration file editing

Settings Highlights

  • Excludes build artifacts and temporary files
  • Configures dotnet solution to GridBuilding.sln
  • Enables C# inlay hints and semantic highlighting
  • Sets up Godot editor integration

File Organization

Working Tests

Tests/Working/PlaceablePOCSLoading/
├── PlaceablePOCSLoadingIsolationTest.cs
├── PlaceablePOCSLoading.IsolationTests.csproj
└── README.md

Main Tests

Tests/GodotTests/GoDotTest/
├── PlaceablePOCSLoadingTest.cs
└── GridBuilding.Core.GodotTests.csproj

Development Workflow

Pattern 1: Internal Dependencies (GDScript)

  • Rule (runtime): Preload directly in the classes that need them. Do not use an internals registry.
  • Obsolete: GBInternals is obsolete (renamed to GBInternals_OBSOLETE). Do not reference it.
  • Prefer direct class_name usage when a type is intended to be referenced broadly.
  • For true internals (scripts that intentionally have no class_name): use a local preload("res://...") constant.
  • Rationale: prevents an internals registry from becoming accidental public API and avoids fragile global preload paths.

Canonical Editing Rule (Plugins vs Demo)

  • Canonical source of truth: this plugin repo under plugins/gameplay/GridPlacement/** (and related plugin repos).
  • Demo projects (e.g. demos/grid_building_dev/godot/**) are validation consumers and are kept in sync via scripts.
  • Sync entrypoints (one-way, plugin -> demo):
    • Config: demos/grid_building_dev/scripts/sync/addon_sync.yaml
    • Run: bash demos/grid_building_dev/scripts/sync/watch_addon_sync.sh
  • Create/modify plugin tests in the plugin repo by default.
  • Exception: demo-only runtime code or demo-only tests/scenarios that are not intended to ship with the plugin.

1. Feature Development

  • Work in isolation tests first (Tests/Working/)
  • Get quick feedback with focused test runs
  • Use toolkits for code analysis

2. Integration Testing

  • Move stable tests to main test suite
  • Run full test suite to verify integration
  • Validate project structure

3. Documentation

  • Update documentation in docs/gridplacement/
  • Build docs to verify changes
  • Commit both code and docs together

Environment Variables (Optional)

You can set these for enhanced functionality:

  • GODOT_BIN - Path to Godot executable
  • TOOLKIT_BIN - Path to toolkit binaries
  • HUGO_BIN - Path to Hugo executable

Troubleshooting

Common Issues

  1. Build Failures: Run validate-structure task first
  2. Test Issues: Check toolkit analysis output for code smells
  3. Documentation: Ensure Hugo dependencies are installed

Getting Help

  • Check the main project README: ../../../../README.md
  • Review toolkit documentation: ../../../toolkits/cs/README.md
  • Consult scripts documentation: ../../../../scripts/README.md

Benefits

This workspace provides:

  • Focused Development: Only GridBuilding-related files visible
  • Quick Access: Toolkits and scripts readily available
  • Integrated Testing: Both isolation and full test suites
  • Documentation Integration: Direct Hugo docs access
  • Performance: Faster builds with targeted compilation

Use this workspace for all GridBuilding plugin development to get the most efficient and focused development experience.