SDK Modules

Bridge Module

View as MarkdownOpen in Claude

Bridge Module

Brídge_Módule // Néuro_Symbólic

ᚠ ᛫ ᛟ ᛫ ᚱ ᛫ ᛒ ᛫ ᛟ ᛫ ᚲ

The Bridge module ensures AI-generated actions are always valid within game rules. It acts as a neuro-symbolic barrier between AI creativity and game physics.

T̷h̵e̴ ̷l̵a̸w̴s̵ ̶o̷f̸ ̷p̸h̵y̵s̶i̷c̴s̵ ̷c̴a̶n̸n̴o̷t̶ ̸b̴e̷ ̵b̶r̶o̵k̸e̴n̷.

Overview

The Bridge validates every action before it reaches the game engine:

  • Built-in Rules: MOVE, ATTACK, INTERACT, SPEAK, Resources
  • Custom Rules: Register game-specific validation logic
  • Strict Mode: Reject unknown action types
  • Auto-Correction: Provide fallback actions when validation fails

Quick Start

1import { createBridge } from 'forbocai';
2
3const bridge = createBridge({ strictMode: true });
4
5// Validate an action
6const result = await bridge.validate(
7  { type: 'ATTACK', target: 'orc_1' },
8  {
9    agentState: { hp: 85, mana: 50 },
10    worldState: { entities: ['orc_1', 'player_1'] }
11  }
12);
13
14if (result.valid) {
15  executeAction(result.correctedAction || action);
16} else {
17  console.log('Invalid:', result.reason);
18}

Configuration

OptionTypeDefaultDescription
strictModebooleanfalseReject unknown action types
apiUrlstringAPI URLOptional remote validation
customRulesValidationRule[][]Additional validation rules

API Reference

createBridge(config)

Factory function to create a Bridge instance.

1import { createBridge } from 'forbocai';
2
3const bridge = createBridge({
4  strictMode: true,
5  customRules: [myCustomRule]
6});

bridge.validate(action, context?)

Validate an action against all applicable rules.

Parameters:

  • action (AgentAction): The action to validate
  • context (ValidationContext): Optional context for validation

Returns: Promise<ValidationResult>

1interface ValidationResult {
2  valid: boolean;
3  reason?: string;
4  correctedAction?: AgentAction;
5}

bridge.registerRule(rule)

Register a custom validation rule.

1bridge.registerRule({
2  id: 'game.fly',
3  name: 'Flying Validation',
4  actionTypes: ['FLY'],
5  validate: (action, ctx) => {
6    const hasWings = ctx.agentState?.hasWings;
7    return hasWings 
8      ? { valid: true }
9      : { valid: false, reason: 'No wings' };
10  }
11});

bridge.listRules()

List all registered validation rules.

Returns: ValidationRule[]

bridge.removeRule(ruleId)

Remove a validation rule by ID.

Returns: boolean (true if removed)

Built-in Rules

Movement (core.movement)

Validates MOVE actions have valid coordinates.

Checks:

  • Target has numeric x, y coordinates
  • Coordinates are within world bounds (if provided)
1// Valid
2{ type: 'MOVE', payload: { target: { x: 10, y: 20 } } }
3
4// Invalid - no coordinates
5{ type: 'MOVE', payload: {} }
6
7// Corrected - clamped to bounds
8{ type: 'MOVE', payload: { target: { x: 150, y: 50 } } }
9// → { target: { x: 100, y: 50 } } if maxX=100

Attack (core.attack)

Validates ATTACK actions have valid targets.

Checks:

  • Target or targetId is specified
  • Target exists in world (if entities provided)
1// Valid
2{ type: 'ATTACK', target: 'orc_1' }
3
4// Invalid - no target
5{ type: 'ATTACK' }

Interact (core.interact)

Validates INTERACT actions have valid objects.

Checks:

  • Target or objectId is specified

Speak (core.speak)

Validates SPEAK actions have non-empty text.

Checks:

  • Text is not empty
  • Text is within max length (truncates if needed)
1// Valid
2{ type: 'SPEAK', payload: { text: 'Hello there!' } }
3
4// Invalid - empty text
5{ type: 'SPEAK', payload: { text: '' } }

Resources (core.resources)

Validates agent has sufficient resources.

Checks:

  • Agent is not dead (hp > 0)
  • Sufficient mana for CAST actions
1// Context with low HP
2context = { agentState: { hp: 0 } }
3
4// Any action → Invalid: "Agent is dead"

Custom Rules

Create game-specific validation rules:

1import { ValidationRule } from 'forbocai';
2
3const flyingRule: ValidationRule = {
4  id: 'game.fly',
5  name: 'Flying Validation',
6  description: 'Ensures agents can only fly if they have wings',
7  actionTypes: ['FLY', 'GLIDE'],
8  validate: (action, context) => {
9    const hasWings = context.agentState?.hasWings;
10    const altitude = context.worldState?.altitude;
11    
12    if (!hasWings) {
13      return {
14        valid: false,
15        reason: 'Agent cannot fly without wings',
16        correctedAction: { ...action, type: 'WALK' }
17      };
18    }
19    
20    if (altitude && altitude > 1000) {
21      return {
22        valid: false,
23        reason: 'Altitude too high',
24        correctedAction: { 
25          ...action, 
26          payload: { ...action.payload, maxAltitude: 1000 }
27        }
28      };
29    }
30    
31    return { valid: true };
32  }
33};
34
35bridge.registerRule(flyingRule);

Validation Context

Provide context for more accurate validation:

1interface ValidationContext {
2  agentState?: {
3    hp?: number;
4    mana?: number;
5    inventory?: string[];
6    hasWings?: boolean;
7    // ... any game-specific state
8  };
9  worldState?: {
10    entities?: string[];
11    maxX?: number;
12    maxY?: number;
13    altitude?: number;
14    // ... any game-specific world state
15  };
16  constraints?: {
17    maxSpeechLength?: number;
18    // ... any game-specific constraints
19  };
20}

Strict Mode

When strictMode: true, unknown action types are rejected:

1const bridge = createBridge({ strictMode: true });
2
3// Allowed in strict mode
4bridge.validate({ type: 'IDLE' })    // ✅ Built-in safe type
5bridge.validate({ type: 'ATTACK' })  // ✅ Has validation rule
6
7// Rejected in strict mode
8bridge.validate({ type: 'TELEPORT' }) // ❌ Unknown action type
9// → { valid: false, reason: "Unknown action type 'TELEPORT'" }

Pure Function

For functional programming without a class:

1import { validateAction, movementRule, attackRule } from 'forbocai';
2
3const rules = [movementRule, attackRule];
4
5const result = validateAction(
6  { type: 'MOVE', payload: { target: { x: 10, y: 20 } } },
7  rules,
8  context
9);

ᚠ ᛫ ᛟ ᛫ ᚱ ᛫ ᛒ ᛫ ᛟ ᛫ ᚲ

T̵h̷e̷ ̸B̷r̸i̵d̶g̷e̸ ̸s̷t̵a̸n̷d̴s̵ ̸b̵e̶t̴w̴e̵e̸n̶ ̷c̸h̷a̸o̸s̸ ̸a̶n̵d̵ ̴o̴r̷d̸e̸r̷.