check_line_of_sight

Instructions

Implementation Reference

• src/registry.ts:655-673 (registration)

  Registration of the 'check_line_of_sight' tool, including name, description, schema conversion, and wrapper handler that validates input and calls the core checkLineOfSight function.

  check_line_of_sight: {
    name: 'check_line_of_sight',
    description: 'Check line of sight between positions with obstacle/cover detection',
    inputSchema: toJsonSchema(checkLineOfSightSchema),
    handler: async (args) => {
      try {
        const validated = checkLineOfSightSchema.parse(args);
        const result = checkLineOfSight(validated);
        return success(result);
      } catch (err) {
        if (err instanceof z.ZodError) {
          const messages = err.errors.map(e => `${e.path.join('.')}: ${e.message}`).join(', ');
          return error(`Validation failed: ${messages}`);
        }
        const message = err instanceof Error ? err.message : String(err);
        return error(message);
      }
    },
  },

• src/modules/spatial.ts:647-686 (schema)

  Zod schema for validating inputs to the check_line_of_sight tool, including positions (coords or IDs), obstacles, creatures, lighting, and special senses.

  export const checkLineOfSightSchema = z.object({
    encounterId: z.string().optional(),
  
    // Position can be coordinates or character ID
    from: PositionSchema.optional(),
    to: PositionSchema.optional(),
    fromId: z.string().optional(),
    toId: z.string().optional(),
  
    // Obstacles (manual or from encounter)
    obstacles: z.array(ObstacleSchema).optional(),
  
    // Creature blocking
    creatures: z.array(CreatureBlockSchema).optional(),
    creaturesBlock: z.boolean().default(false),
  
    // Lighting and senses
    lighting: LightSchema.optional(),
    darkvision: z.number().optional(),
    senses: z.array(SenseSchema).optional(),
    blindsightRange: z.number().optional(),
    tremorsenseRange: z.number().optional(),
  }).refine((data) => {
    // Must have from position or fromId
    const hasFrom = data.from !== undefined || data.fromId !== undefined;
    // Must have to position or toId
    const hasTo = data.to !== undefined || data.toId !== undefined;
    return hasFrom && hasTo;
  }, {
    message: 'Must provide from/to positions or fromId/toId',
  }).refine((data) => {
    // If using IDs, must have encounterId
    if ((data.fromId || data.toId) && !data.encounterId) {
      return false;
    }
    return true;
  }, {
    message: 'encounterId required when using fromId/toId',
  });

• src/modules/spatial.ts:820-1016 (handler)

  Core implementation of check_line_of_sight: resolves observer/target positions, detects blocking/cover from obstacles/creatures, accounts for senses/lighting, computes cover bonuses, generates detailed ASCII visualization.

  export function checkLineOfSight(input: CheckLineOfSightInput): string {
    const content: string[] = [];
  
    // Resolve positions
    let fromPos: Position;
    let toPos: Position;
    let fromName: string | undefined;
    let toName: string | undefined;
  
    if (input.fromId && input.encounterId) {
      const participant = getEncounterParticipant(input.encounterId, input.fromId);
      if (!participant) {
        throw new Error(`Participant not found: ${input.fromId}`);
      }
      fromPos = participant.position || { x: 0, y: 0, z: 0 };
      fromName = participant.name;
    } else if (input.from) {
      fromPos = { x: input.from.x, y: input.from.y, z: input.from.z ?? 0 };
    } else {
      throw new Error('From position required');
    }
  
    if (input.toId && input.encounterId) {
      const participant = getEncounterParticipant(input.encounterId, input.toId);
      if (!participant) {
        throw new Error(`Participant not found: ${input.toId}`);
      }
      toPos = participant.position || { x: 0, y: 0, z: 0 };
      toName = participant.name;
    } else if (input.to) {
      toPos = { x: input.to.x, y: input.to.y, z: input.to.z ?? 0 };
    } else {
      throw new Error('To position required');
    }
  
    // Calculate distance
    const dx = toPos.x - fromPos.x;
    const dy = toPos.y - fromPos.y;
    const dz = (toPos.z ?? 0) - (fromPos.z ?? 0);
    const distance = Math.sqrt(dx * dx + dy * dy + dz * dz) * 5;
  
    // Build header
    content.push(centerText('LINE OF SIGHT', LOS_DISPLAY_WIDTH));
    content.push('');
  
    // Show positions
    if (fromName) {
      content.push(`From: ${fromName} (${fromPos.x}, ${fromPos.y}, ${fromPos.z ?? 0})`);
    } else {
      content.push(`From: (${fromPos.x}, ${fromPos.y}, ${fromPos.z ?? 0})`);
    }
  
    if (toName) {
      content.push(`To: ${toName} (${toPos.x}, ${toPos.y}, ${toPos.z ?? 0})`);
    } else {
      content.push(`To: (${toPos.x}, ${toPos.y}, ${toPos.z ?? 0})`);
    }
  
    content.push(`Distance: ${Math.round(distance)} feet`);
    content.push('');
    content.push(BOX.LIGHT.H.repeat(LOS_DISPLAY_WIDTH));
    content.push('');
  
    // Handle same position
    if (distance === 0) {
      content.push(centerText('CLEAR - SAME POSITION', LOS_DISPLAY_WIDTH));
      content.push('');
      content.push('Observer and target at same position.');
      return createBox('LINE OF SIGHT', content);
    }
  
    // Collect all obstacles to check
    const allObstacles = [...(input.obstacles || [])];
  
    // Get terrain obstacles from encounter if available
    // (For now, just use provided obstacles - encounter terrain integration pending)
  
    // Check for blocking and cover
    let coverLevel: CoverLevel = 'none';
    let blockingObstacle: typeof allObstacles[0] | undefined;
    let blockingCreature: { size: string } | undefined;
  
    // Check static obstacles
    for (const obstacle of allObstacles) {
      const obstacleCover = calculateCoverFromObstacle(obstacle, fromPos, toPos);
      if (obstacleCover !== null) {
        coverLevel = determineCoverLevel(coverLevel, obstacleCover);
        if (obstacleCover !== 'none') {
          blockingObstacle = obstacle;
        }
      }
    }
  
    // Check creature blocking
    if (input.creaturesBlock && input.creatures) {
      for (const creature of input.creatures) {
        if (isOnLine(fromPos, toPos, creature)) {
          const creatureCover = getCreatureCover(creature.size);
          coverLevel = determineCoverLevel(coverLevel, creatureCover);
          if (creatureCover !== 'none') {
            blockingCreature = creature;
          }
        }
      }
    }
  
    // Handle special senses
    if (input.senses?.includes('blindsight') && input.blindsightRange) {
      if (distance <= input.blindsightRange) {
        content.push('BLINDSIGHT Active');
        content.push('');
        content.push(`blindsight range: ${input.blindsightRange} ft (target within range)`);
        content.push('Can perceive through normal obstacles.');
        content.push('');
        content.push(BOX.LIGHT.H.repeat(LOS_DISPLAY_WIDTH));
        content.push('');
      }
    }
  
    if (input.senses?.includes('tremorsense') && input.tremorsenseRange) {
      content.push('TREMORSENSE NOTES');
      content.push('');
      if ((toPos.z ?? 0) > 0) {
        content.push(`Target is airborne (z=${toPos.z ?? 0}) - flying creatures`);
        content.push('cannot be detected by tremorsense.');
      } else if (distance <= input.tremorsenseRange) {
        content.push(`Range: ${input.tremorsenseRange} ft (target within range)`);
      }
      content.push('');
      content.push(BOX.LIGHT.H.repeat(LOS_DISPLAY_WIDTH));
      content.push('');
    }
  
    // Handle lighting
    if (input.lighting === 'darkness') {
      content.push('LIGHTING: DARKNESS');
      content.push('');
      if (input.darkvision) {
        if (distance <= input.darkvision) {
          content.push(`Darkvision range: ${input.darkvision} ft`);
          content.push('Target within darkvision range (dim light for you).');
        } else {
          content.push(`Darkvision range: ${input.darkvision} ft`);
          content.push(`Target at ${Math.round(distance)} ft - heavily obscured!`);
        }
      } else {
        content.push('No darkvision - target is heavily obscured.');
      }
      content.push('');
      content.push(BOX.LIGHT.H.repeat(LOS_DISPLAY_WIDTH));
      content.push('');
    }
  
    // Display result
    content.push(centerText('RESULT', LOS_DISPLAY_WIDTH));
    content.push('');
  
    if (coverLevel === 'total') {
      content.push('STATUS: BLOCKED');
      content.push('');
      content.push('Total cover - no line of sight!');
      if (blockingObstacle) {
        content.push(`Blocked by: ${blockingObstacle.type} at (${blockingObstacle.x}, ${blockingObstacle.y})`);
      }
    } else if (coverLevel === 'three_quarters') {
      content.push('STATUS: THREE-QUARTERS COVER');
      content.push('');
      content.push('Target has three-quarters cover.');
      content.push(`AC Bonus: +${COVER_BONUSES.three_quarters}`);
      content.push(`Dex Save Bonus: +${COVER_BONUSES.three_quarters}`);
      if (blockingObstacle) {
        content.push(`Cover from: ${blockingObstacle.type}`);
      }
      if (blockingCreature) {
        content.push(`Cover from: ${blockingCreature.size} creature`);
      }
    } else if (coverLevel === 'half') {
      content.push('STATUS: HALF COVER');
      content.push('');
      content.push('Target has half cover.');
      content.push(`AC Bonus: +${COVER_BONUSES.half}`);
      content.push(`Dex Save Bonus: +${COVER_BONUSES.half}`);
      if (blockingObstacle) {
        content.push(`Cover from: ${blockingObstacle.type}`);
      }
      if (blockingCreature) {
        content.push(`Cover from: ${blockingCreature.size} creature`);
      }
    } else {
      content.push('STATUS: CLEAR');
      content.push('');
      content.push('Line of sight is unobstructed.');
    }
  
    const title = coverLevel === 'total' ? 'BLOCKED' : 'LINE OF SIGHT';
    return createBox(title, content);
  }

• src/modules/spatial.ts:711-723 (helper)

  Utility function to get numerical AC/Dex save bonuses from cover levels (0, +2, +5, Infinity for total).

  export function getCoverBonus(cover: string): number {
    switch (cover) {
      case 'half':
        return COVER_BONUSES.half;
      case 'three_quarters':
        return COVER_BONUSES.three_quarters;
      case 'total':
      case 'full':
        return Infinity; // Target can't be directly targeted
      default:
        return 0;
    }
  }

• src/modules/spatial.ts:1022-1059 (helper)

  Core geometry helper: determines if an obstacle/creature intersects the line of sight using line projection and grid tolerance.

  function isOnLine(
    from: Position,
    to: Position,
    point: Position
  ): boolean {
    // Calculate distance from point to line
    const dx = to.x - from.x;
    const dy = to.y - from.y;
    const dz = (to.z ?? 0) - (from.z ?? 0);
  
    const length = Math.sqrt(dx * dx + dy * dy + dz * dz);
    if (length === 0) return false;
  
    // Vector from 'from' to 'point'
    const px = point.x - from.x;
    const py = point.y - from.y;
    const pz = (point.z ?? 0) - (from.z ?? 0);
  
    // Project point onto line
    const t = (px * dx + py * dy + pz * dz) / (length * length);
  
    // Check if projection is between from and to
    if (t < 0 || t > 1) return false;
  
    // Calculate closest point on line
    const closestX = from.x + t * dx;
    const closestY = from.y + t * dy;
    const closestZ = (from.z ?? 0) + t * dz;
  
    // Calculate distance from point to closest point on line
    const distX = point.x - closestX;
    const distY = point.y - closestY;
    const distZ = (point.z ?? 0) - closestZ;
    const dist = Math.sqrt(distX * distX + distY * distY + distZ * distZ);
  
    // Within 1 grid square (5 feet / 5 = 1 unit) tolerance
    return dist <= 1;
  }