A modern, type-safe GraphQL API for The Forgotten Server (TFS), built with Go and gqlgen. This API provides a complete interface for managing accounts, players, guilds, houses, and marketplace operations in your OTServer.

Compatible with: TFS v1.4.2

• 🔐 Account Management - Complete CRUD operations for accounts, bans, and storage
• 👥 Player System - Player creation, statistics, deaths tracking, and storage management
• 🏰 Guild System - Guild management with ranks, memberships, invites, and war tracking
• 🏠 House Management - House listings, bidding system, and ownership tracking
• 💰 Market System - Marketplace offers and transaction history
• 🏙️ Town System - Town management and positioning
• ✅ Full Test Coverage - Comprehensive unit tests with mocked database
• 🚀 Type-Safe - Generated types and resolvers using gqlgen
• 📊 GraphQL Playground - Interactive API exploration and testing

• Go 1.24+ - Programming language
• gqlgen - GraphQL server library and code generator
• MySQL - Database (compatible with TFS schema)
• sqlx - Enhanced SQL database driver
• Chi - HTTP router
• go-sqlmock - SQL mock driver for testing

• Go 1.24 or higher
• MySQL 5.7+ or MariaDB 10.2+
• The Forgotten Server v1.4.2 database schema

1. Clone the repository

   git clone https://github.com/glinharesb/forgottenserver-graphql-api.git
   cd forgottenserver-graphql-api

2. Install dependencies

   go mod download

3. Set up the database

   This API requires a TFS v1.4.2 database. Set up your database using the schema from TFS v1.4.2:

   mysql -u username -p database_name < forgottenserver/schema.sql

4. Configure environment

   Copy the example environment file and configure it:

   cp .env.example .env

   Edit .env with your database credentials:

   DB_HOST=localhost
   DB_PORT=3306
   DB_USER=your_username
   DB_PASSWORD=your_password
   DB_NAME=your_database
   SERVER_PORT=8080

5. Run the server

   make run

   Or build and run manually:

   go build -o server ./cmd/server
   ./server

The API will be available at http://localhost:8080/graphql with an interactive playground at http://localhost:8080/

.
├── cmd/
│   └── server/          # Application entry point
├── internal/
│   ├── config/          # Configuration management
│   ├── database/        # Database connection
│   ├── graph/           # GraphQL schema and resolvers
│   │   ├── model/       # Generated GraphQL models
│   │   └── *.graphqls   # GraphQL schema definitions
│   └── models/          # Business logic and repositories
│       ├── account.go
│       ├── player.go
│       ├── guild.go
│       ├── house.go
│       ├── market.go
│       └── ...
├── .env.example        # Example environment configuration
├── gqlgen.yml          # GraphQL code generation config
├── Makefile            # Build and development commands
└── README.md

type Query {
  # Accounts
  account(id: ID!): Account
  accounts(limit: Int = 10): [Account!]!

  # Players
  player(id: ID!): Player
  players(accountId: ID!): [Player!]!

  # Guilds
  guild(id: ID!): Guild
  guilds: [Guild!]!
  guildWars(guildId: ID): [GuildWar!]!

  # Houses
  house(id: ID!): House
  houses(townId: ID): [House!]!

  # Market
  marketOffers(itemType: Int): [MarketOffer!]!
  marketHistory(playerId: ID!): [MarketHistory!]!

  # Towns
  town(id: ID!): Town
  towns: [Town!]!
}

type Mutation {
  # Accounts
  createAccount(input: CreateAccountInput!): Account!
  banAccount(input: BanAccountInput!): AccountBan!

  # Players
  createPlayer(input: CreatePlayerInput!): Player!

  # Guilds
  createGuild(input: CreateGuildInput!): Guild!
  inviteToGuild(guildId: ID!, playerId: ID!): Boolean!
  acceptGuildInvite(guildId: ID!, playerId: ID!): Boolean!

  # Houses
  bidHouse(houseId: ID!, playerId: ID!, bidAmount: Int!): House!

  # Market
  createMarketOffer(input: CreateMarketOfferInput!): MarketOffer!

  # Towns
  createTown(input: CreateTownInput!): Town!
}

query GetAccount {
  account(id: "1") {
    id
    name
    email
    players {
      id
      name
      level
      vocation
    }
  }
}

mutation CreatePlayer {
  createPlayer(input: {
    name: "Warrior"
    accountId: 1
    sex: 1
    vocation: 4
  }) {
    id
    name
    level
    health
    healthMax
  }
}

query GetGuild {
  guild(id: "1") {
    id
    name
    owner {
      id
      name
    }
    ranks {
      id
      name
      level
    }
    members {
      player {
        name
        level
      }
      rank {
        name
      }
    }
  }
}

query GetMarketOffers {
  marketOffers(itemType: 2160) {
    id
    player {
      name
    }
    amount
    price
    created
  }
}

make build          # Build the application
make run            # Run the application
make test           # Run all tests
make test-coverage  # Run tests with coverage report
make generate       # Regenerate GraphQL code
make clean          # Clean build artifacts
make tidy           # Tidy Go modules
make docker-build   # Build Docker image

# Run all tests
make test

# Run tests with coverage
make test-coverage

# Run tests for specific package
go test ./internal/models/...

After modifying the GraphQL schema (internal/graph/schema.graphqls):

make generate

This will regenerate:

• Resolver interfaces
• Model types
• GraphQL execution code

The project includes comprehensive test coverage with mocked database operations:

• Model Tests - Unit tests for all repository methods
• Resolver Tests - Integration tests for GraphQL resolvers
• Mock Database - Using go-sqlmock for isolated testing

Example test output:

✓ 27 tests in internal/graph
✓ 30 tests in internal/models

The API is compatible with the TFS v1.4.2 database schema. Key tables include:

• accounts - User accounts
• players - Player characters
• guilds - Guild information
• guild_ranks - Guild hierarchy
• guild_membership - Player-guild relationships
• houses - House data
• market_offers - Active market listings
• market_history - Completed transactions
• towns - Town locations
• player_deaths - Death history

Configure the application using environment variables or a .env file:

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

• Write tests for new features
• Follow Go best practices and conventions
• Update documentation when adding new queries/mutations
• Run make lint before committing
• Ensure all tests pass with make test

This project is licensed under the MIT License - see the LICENSE file for details.

• The Forgotten Server - The OTServer distribution this API is built for
• gqlgen - GraphQL library for Go
• Open Tibia - Community and resources

• 📖 GraphQL Playground - Interactive API documentation
• 🐛 Issue Tracker
• 💬 Discussions

Built with ❤️ for the Open Tibia community