{'>'}_
English 繁體中文 日本語 한국어 Deutsch Español Français
Login

landsandboat-ffxi

Shuu-37/xi-ai-skill

Expert knowledge of Final Fantasy XI private server development using LandSandBoat codebase. Use when working with FFXI game mechanics, LandSandBoat source code, database schema, Lua scripting, GM tools, or server administration.

0 stars
0 forks
Shell
14 views
View on GitHub Add to Favorites

SKILL.md

name: landsandboat-ffxi description: Expert knowledge of Final Fantasy XI private server development using LandSandBoat codebase. Use when working with FFXI game mechanics, LandSandBoat source code, database schema, Lua scripting, GM tools, or server administration. allowed-tools: Read, Grep, Glob, WebFetch, Bash, Edit, Write

LandSandBoat FFXI Development Skill

Expert knowledge base for Final Fantasy XI private server development using the LandSandBoat codebase.

When to Activate This Skill

Claude should activate this skill when the user's request involves:

  • LandSandBoat Development: Server configuration, troubleshooting, or modifications
  • FFXI Game Mechanics: Combat systems, status effects, abilities, magic, crafting
  • Database Work: Schema design, queries, character data, game data tables
  • Lua Scripting: Zone scripts, NPCs, quests, missions, mob behaviors
  • GM Tools & APIs: Building admin tools, player management, server utilities
  • Network Protocols: FFXI packet structures, IPC, HTTP API integration
  • Server Architecture: Understanding multi-process design, ZeroMQ, C++20 implementation

Available Documentation

This skill provides comprehensive reference documentation in the docs/ directory:

Core Documentation Files

  1. architecture-overview.md (24 KB)

    • Multi-process server design (login, map, world, search servers)
    • Technology stack (C++20, Lua, MariaDB, ZeroMQ)
    • Build system and configuration
    • Module system for extensions

  2. gameplay-systems.md (32 KB)

    • Combat system (physical, magical, ranged)
    • Entity system (characters, mobs, NPCs, pets, trusts)
    • Status effects and buffs
    • Quest and mission systems
    • Zone management and navigation
    • NPC interaction patterns

  3. database.md (56 KB) - Primary reference for database work

    • Complete schema documentation for 126+ tables
    • Table relationships and foreign keys
    • Character data structures
    • Game data (items, mobs, abilities, spells)
    • Economy systems (auction house, synth recipes)
    • Binary blob field documentation

  4. networking.md (28 KB)

    • Network architecture and ports
    • IPC via ZeroMQ (localhost:54003)
    • Optional HTTP API (disabled by default)
    • Packet structures (C2S and S2C)
    • Security considerations

  5. scripting.md (16 KB)

    • Lua integration architecture
    • Zone script structure (OnInitialize, OnZoneIn, onTrigger, etc.)
    • Entity interaction patterns
    • Common scripting patterns and examples
    • Enumerations and constants

  6. utilities.md (8 KB)

    • Python development tools (dbtool.py, announce.py, etc.)
    • Database management utilities
    • CI/CD tools and testing utilities

Setup Instructions

First-Time Setup

When this skill is first activated, verify if the LandSandBoat reference codebase is available:

  1. Check for reference directory: Look for reference/ directory in the skill folder
  2. If missing: Offer to run the setup script to clone the complete LandSandBoat codebase
  3. Run setup: Execute ./scripts/setup-reference.sh from the skill directory

The reference directory provides:

  • Complete C++20 source code (~26% of codebase)
  • All 297 zone Lua scripts (~63% of codebase)
  • 126+ SQL schema files
  • Python development tools
  • Configuration examples

Path References

All documentation and reference paths use the pattern: landsandboat-skill/path/to/file

Examples:

  • landsandboat-skill/docs/database.md - Database schema reference
  • landsandboat-skill/reference/src/map/zone.cpp - Zone C++ implementation
  • landsandboat-skill/reference/scripts/zones/ - Zone Lua scripts

Working with This Skill

Strategy for Different Tasks

Building GM Tools or APIs

  1. Start with architecture: Read docs/architecture-overview.md to understand server processes
  2. Database access: Reference docs/database.md for schema (tables, relationships, constraints)
  3. Network options: Check docs/networking.md for:
    • Direct database access (most common)
    • HTTP API integration (if enabled)
    • ZeroMQ IPC (for advanced server integration)
  4. Examples: Review reference/tools/*.py for Python tool patterns

Recommended stack: TypeScript + TanStack Query for modern API development

Lua Scripting

  1. Patterns: Read docs/scripting.md for architecture and common patterns
  2. Reference code: Browse reference/scripts/zones/ for real examples
  3. Enumerations: Check reference/scripts/enum/ for game constants
  4. Globals: Review reference/scripts/globals/ for shared functions

Understanding Game Mechanics

  1. Overview: Start with docs/gameplay-systems.md for high-level concepts
  2. C++ implementation: Reference reference/src/map/ for core engine logic
  3. Lua formulas: Check reference/scripts/globals/ for damage calculations, status effects
  4. Database data: Query game data tables documented in docs/database.md

Database Design & Queries

  1. Schema reference: Use docs/database.md as primary reference (56 KB, comprehensive)
  2. Table relationships: Understand foreign keys (e.g., charid → chars.charid)
  3. Binary blobs: Character missions, abilities, key items stored as binary (see schema docs)
  4. Constraints: Respect game limits (inventory slots, stacking, job restrictions)
  5. Transactions: Always use transactions for multi-table modifications

Network Protocol & Packets

  1. Architecture: Read docs/networking.md for multi-server communication
  2. Packet definitions: Reference reference/src/map/packets/ for C++ structures
  3. IPC patterns: Check reference/src/common/ipc.h for message types
  4. Security: Note that IPC is localhost-only, HTTP API disabled by default

Important Considerations

Data Integrity

  • Character data has complex interdependencies across multiple tables
  • Binary blob fields (missions, abilities) require careful parsing
  • Always backup database before bulk operations
  • Test on development environment first

Game Balance

  • Server rates configured in reference/settings/default/main.lua
  • Era-specific settings affect gameplay (level caps, job abilities, expansion content)
  • Use module system for customizations without modifying core

Security

  • Database credentials in reference/settings/default/network.lua
  • IPC bound to localhost only (no external access)
  • HTTP API disabled by default - requires explicit enabling
  • DDoS protection settings available in network config

Performance

  • Lua scripts are hot-reloadable (no server restart needed)
  • Optimize database queries (use indexed columns)
  • ZeroMQ provides high-performance IPC
  • Multiple map servers can run for load distribution

Common Use Cases

Player Management

  • Query chars table for character data
  • Modify stats, inventory, position
  • Track sessions in accounts_sessions

Item Distribution

  • Insert into char_inventory with proper item IDs
  • Respect stacking limits and container slots
  • Validate items exist in item_basic table

Server Announcements

  • Use reference/tools/announce.py
  • Or integrate with World Server IPC

Economy Monitoring

  • Query auction_house for transactions
  • Track price trends and market activity
  • Check char_points for currency tracking

World State Management

  • Conquest system tables
  • Campaign and besieged status
  • Zone weather and time-of-day

Additional Resources

  • LandSandBoat Repository: https://github.com/LandSandBoat/server
  • GitHub Wiki: 48+ pages on installation, configuration, development
  • Module Development: Guides for Lua, C++, and SQL modules
  • Community Discord: Active development community

Debugging and Troubleshooting

If Claude isn't using this skill effectively:

  1. Verify skill activation: Check that request mentions FFXI or LandSandBoat
  2. Documentation access: Ensure docs/ directory is readable
  3. Reference code: Run setup script if reference/ directory is missing
  4. Specific queries: Provide context (e.g., "using LandSandBoat" or "FFXI private server")

Version Information

  • LandSandBoat Version: Latest stable (reference cloned from main branch)
  • Skill Version: 1.0.0
  • Last Updated: 2025-11-05
  • Documentation Coverage: ~164 KB across 6 primary documentation files

README

LandSandBoat FFXI Development Skill

A Claude Code skill that provides expert knowledge for Final Fantasy XI private server development using the LandSandBoat codebase.

What is This?

This skill enables Claude to automatically assist with FFXI private server development by providing:

  • Comprehensive documentation (~164 KB) covering architecture, gameplay systems, database schema, networking, scripting, and utilities
  • Complete reference codebase access to LandSandBoat's C++20 and Lua implementation
  • Expert context for building GM tools, APIs, and custom content

When you mention FFXI, LandSandBoat, or related concepts, Claude automatically activates this skill and gains access to specialized knowledge.

Features

Documentation Coverage

  • Architecture Overview - Multi-process server design, technology stack, build system
  • Gameplay Systems - Combat, entities, status effects, quests, missions, zones
  • Database Schema (56 KB) - Complete reference for 126+ tables with relationships
  • Networking - IPC, HTTP API, packet structures, protocols
  • Scripting - Lua integration, patterns, examples
  • Utilities - Python tools for server management

Reference Codebase

Access to complete LandSandBoat source:

  • C++20 core engine (~26% of codebase)
  • Lua scripting layer (~63% of codebase)
  • 297 zone implementations
  • 126+ SQL schema files
  • Python development tools

Installation

Option 1: Personal Installation (Recommended)

Install once and use across all your projects:

# Clone to your personal Claude skills directory
git clone https://github.com/your-org/landsandboat-skill ~/.claude/skills/landsandboat-ffxi

# Navigate to skill directory
cd ~/.claude/skills/landsandboat-ffxi

# Run setup to download LandSandBoat reference codebase
./scripts/setup-reference.sh

On Windows (Git Bash or WSL):

git clone https://github.com/your-org/landsandboat-skill ~/AppData/Roaming/Claude/skills/landsandboat-ffxi
cd ~/AppData/Roaming/Claude/skills/landsandboat-ffxi
./scripts/setup-reference.sh

Option 2: Project-Level Installation

For teams working on FFXI projects together:

# From your project root
git clone https://github.com/your-org/landsandboat-skill .claude/skills/landsandboat-ffxi

# Run setup
cd .claude/skills/landsandboat-ffxi
./scripts/setup-reference.sh

Team members will receive the skill when they pull changes.

Option 3: Plugin (Future)

Once published to Claude Code plugin marketplace:

claude install landsandboat-ffxi

Usage

Once installed, Claude automatically activates this skill when you mention:

  • "LandSandBoat"
  • "LSB"
  • "FFXI private server"
  • "Final Fantasy XI development"
  • Game mechanics (combat, quests, NPCs)
  • Database tables (chars, mob_spawn_points, etc.)
  • Lua scripting for zones

Example Interactions

You: I need to create a GM tool to manage player inventory

Claude: [Activates landsandboat-ffxi skill]
I'll help you build a GM tool for inventory management. Let me reference
the database schema for character inventory...
[References docs/database.md and provides implementation]

You: How do I script an NPC that starts a quest in LandSandBoat?

Claude: [Activates landsandboat-ffxi skill]
I'll show you the pattern for quest-giving NPCs based on LandSandBoat
scripting conventions...
[References docs/scripting.md and reference/scripts/zones/ examples]

You: What's the database structure for mob spawns?

Claude: [Activates landsandboat-ffxi skill]
The mob spawn system uses several related tables. Let me walk you through
the schema...
[References docs/database.md with detailed table relationships]

Repository Structure

landsandboat-skill/
├── SKILL.md                    # Skill definition with YAML frontmatter
├── README.md                   # This file
├── docs/                       # AI-friendly documentation (164 KB)
│   ├── architecture-overview.md
│   ├── gameplay-systems.md
│   ├── database.md            # Primary database reference (56 KB)
│   ├── networking.md
│   ├── scripting.md
│   └── utilities.md
├── scripts/
│   └── setup-reference.sh     # Clone LandSandBoat codebase
└── reference/                  # LandSandBoat source (gitignored)
    ├── src/                   # C++20 source
    ├── scripts/               # Lua scripts
    ├── sql/                   # Schema files
    └── tools/                 # Python utilities

Reference Codebase Setup

The reference/ directory contains the complete LandSandBoat codebase for AI reference. It's gitignored and must be set up locally.

First-Time Setup

cd ~/.claude/skills/landsandboat-ffxi  # or your skill location
./scripts/setup-reference.sh

This clones the latest LandSandBoat repository into reference/.

Updating Reference Code

cd ~/.claude/skills/landsandboat-ffxi
./scripts/setup-reference.sh  # Pulls latest changes if already cloned

What Gets Downloaded

  • Complete C++20 source code
  • All 297 zone Lua scripts
  • 126+ SQL schema files
  • Python development tools
  • Configuration examples
  • LandSandBoat documentation

Size: ~200-300 MB

Requirements

  • Claude Code: This skill is designed for Claude Code CLI
  • Git: Required for cloning the reference codebase
  • Disk Space: ~300 MB for reference codebase
  • OS: Works on Linux, macOS, Windows (with Git Bash or WSL)

Common Use Cases

Building GM Tools

  • Player management interfaces
  • Item distribution tools
  • Server announcement systems
  • Economy monitoring dashboards

Lua Scripting

  • Zone scripts (NPCs, mobs, events)
  • Quest and mission implementations
  • Custom content (BCNMs, dynamis, etc.)
  • Status effect behaviors

Database Work

  • Schema design for custom content
  • Data migration scripts
  • Player data queries and reports
  • Game data management

API Development

  • RESTful APIs for web interfaces
  • Discord bot integrations
  • Admin panel backends
  • Analytics and monitoring

Advantages Over Traditional Documentation

Automatic Activation

No need to manually reference docs - Claude knows when to use this skill.

Context-Aware

Claude understands relationships between systems (e.g., how database tables relate to C++ entities and Lua scripts).

Comprehensive

164 KB of structured documentation plus complete source code access.

Always Available

Install once, works across all your FFXI projects.

Team Sharing

Commit to .claude/skills/ in your repository for team-wide access.

Updating the Skill

To get the latest documentation and improvements:

cd ~/.claude/skills/landsandboat-ffxi
git pull origin main

To update the reference codebase:

./scripts/setup-reference.sh

Contributing

Contributions welcome! To improve this skill:

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes:
    • Update documentation in docs/
    • Improve SKILL.md instructions
  4. Test with Claude Code
  5. Submit a pull request

Documentation Guidelines

  • Keep docs AI-friendly (clear structure, examples, relationships)
  • Use code references with file:line format
  • Provide context for complex systems
  • Include common pitfalls and considerations

Troubleshooting

Claude Isn't Activating the Skill

Check installation location:

ls ~/.claude/skills/landsandboat-ffxi/SKILL.md

Verify YAML frontmatter is valid:

head -n 5 ~/.claude/skills/landsandboat-ffxi/SKILL.md

Be more explicit: Instead of: "How do I create an NPC?" Try: "How do I create an NPC in LandSandBoat?"

Reference Directory Missing

Run the setup script:

cd ~/.claude/skills/landsandboat-ffxi
./scripts/setup-reference.sh

Permission Issues (Windows)

Use Git Bash or WSL to run the setup script. PowerShell may have issues with the bash script.

Skill Path Issues

Ensure the skill is in one of these locations:

  • ~/.claude/skills/landsandboat-ffxi/ (personal)
  • .claude/skills/landsandboat-ffxi/ (project-level)

License

This skill repository is MIT licensed. The LandSandBoat reference codebase in reference/ maintains its original GPL-3.0 license.

Related Resources

Version

Skill Version: 1.0.0 Last Updated: 2025-11-05 LandSandBoat Version: Latest stable (main branch)

Built with ❤️ for the FFXI private server development community