Tibia

A repository for all things Tibia.

Where are the NPCs?

They are here!

• /data/npcs/text/

• Talesoftibia.com: Open Source

• Discord: Explorer Society

• Search Transcripts: NPSearch

• Search Books: LIBSearch

• Research: talesoftibia, reddit

• All Transcripts: ↗

The data/npcs/text/ directory and its content is used by NPSearch
The data/books/book_database.json contains 1370~ books and is used by LIBSearch

Tales of Tibia: Project Overview

1. Tales of Tibia: Project Overview
   1. What is Tales of Tibia?
2. The Search Tools
   1. How to Contribute
   2. Project Structure
3. Data and Image Endpoints
   1. resources.talesoftibia.com
4. Hotkey Mania: Detailed Guide
   1. What is Hotkey Mania?
   2. How Hotkey Mania Works
   3. Setting Up Hotkey Mania
   4. Using Hotkey Mania
5. NPC Transcripts: Contribution Guide
   1. Collection Process
   2. Basic Format
   3. Grouping Conversations
   4. Additional Tips
   5. Helper Script
6. Adding new NPCs and Books: Contribution Guide
   1. NPCs
   2. Books
7. Contributors
8. Legal Note

What is Tales of Tibia?

Tales of Tibia is a passion-project that provides tools and resources for the Tibia gaming community, to be able to read the various tales in Tibia, be it from books, NPC conversations or from user-generated research.

The main components are:

1. npsearch: A tool for searching and viewing NPC transcripts.
2. libsearch: A tool for searching and viewing in-game books.
   • See tools here: GitHub
3. Magic Web Explorer: A map tool with cyclopedia, catered to explore the Magic Web.
   • See tool here: GitHub
4. Blog: A collection of updates, mysteries, stories, guides, and research.
5. GitHub: A repository of NPC transcripts and book data for community contributions.
   • See repository here: GitHub

The Search Tools

For a simple demonstration, visit services.

The NPC and book data is sourced from various Tibia community resources, this project, and compiled into a structured database. When adding new data, it's then automatically validated, processed, and published for use.

1. Data Collection:

   • NPC transcripts are sourced from tibiasecrets.com, community contributions, and a custom hotkey spamming method. Some transcripts from English and Brazilian Wiki are also used.
     • New transcripts come from hotkey spamming, and is the most reliable method.
   • Book data is compiled from English and Brazilian Tibia Wikis, with additional harmonization, metadata and missing books added.

2. Data Processing:

   • Automated workflows process and validate the data.
   • GitHub Actions update file mappings, sync NPC data, and generate tree views upon approved pull requests.
   • All data/npcs/text/*.txt files are compiled into data/npcs/npc_transcript_database.json and published to GitHub Pages and Cloudflare R2.

3. User Interface:

   • The search interfaces, designed by GABRO, mimic Tibia's aesthetic.
   • npsearch and libsearch fetch data from JSON files hosted on Cloudflare R2 to perform client-side searches.

How to Contribute

1. NPC Transcripts:

See NPC Transcripts: Contribution Guide for more detailed guidelines.
But in essence, you can contribute by:

• Checking the docs/npc_trees/unverified_empty_transcripts.md list for missing transcripts.
• Use the "Hotkey Mania" method for complete* documentation.
• Create a pull request with your changes.
  • You may also send missing data on e.g. Discord or Reddit. It will be highly appreciated.

2. Book Data:

   • Contributions to the book database are welcome, read how-to here: instructions

3. Tool Development:

   • Raise an issue, reach out via Discord or Reddit to discuss new tool ideas or features.

Project Structure

1. GitHub Repository:

   • data/npcs/text/: Contains NPC transcripts (used by npsearch).
   • data/books/book_database.json: Contains book data (used by libsearch).
   • src/: Python scripts for data processing and validation.
   • .github/workflows/: GitHub Actions for automated processes.

2. Directory Structure:

tibia/
├── data/
│   ├── books/
│   │   ├── book_database.json
│   │   └── book_image_mapping.json
│   ├── npcs/
│   │   ├── npc_metadata.json
│   │   ├── npc_transcript_database.json
│   │   ├── npc_verification_mapping.json
│   │   └── text/
│   │       └── [NPC text files organized by <area>/<subarea>]
│   └── status/
│       └── [project status files]
├── docs/
│   ├── npc_trees/
│   │   └── [NPC tree structures]
│   └── [other documentation files]
├── .github/
│   └── workflows/
│       ├── deploy_resources.yml
│       ├── update_and_process_npc_data.yml
│       ├── update_npc_status_on_pr_merge.yml
│       └── validate_npc_file_structure.yml
├── src/
│   ├── scripts/
│   │   ├── gha/
│   │   │   ├── generate_book_image_mapping.py
│   │   │   ├── generate_npc_status_report.py
│   │   │   ├── update_npc_location_metadata.py
│   │   │   ├── generate_npc_trees.py
│   │   │   ├── compile_npc_transcript_database.py
│   │   │   ├── update_npc_file_and_verification_mapping.py
│   │   │   ├── update_project_status.py
│   │   │   └── validate_npc_file_structure.py
│   │   └── utils/
│   │       ├── mapper_to_tibiamaps.py
│   │       └── sanitize.py
│   └── [other source code modules]
├── hotkeys.json
└── [other project files]

1. GitHub Workflows:
   • Pull requests trigger validation checks.
     • validate_npc_file_structure.yml
   • Approved changes update file mappings, sync data, compile NPC database, and regenerate documentation.
     • update_and_process_npc_data.yml
   • Changes are then published to GitHub Pages, and Cloudflare R2 on resources.talesoftibia.com
     • deploy_resources.yml
   • Another workflow creates a notification on Discord, as well as an update to individual contributions on GitHub
     • update_npc_status_on_pr_merge.yml

Data and Image Endpoints

The database and images are hosted by Cloudflare in an R2 Bucket, which is accessible on a dedicated subdomain, resources.talesoftibia.com

resources.talesoftibia.com

Prepend https://resources.talesoftibia.com to the following paths:

1. JSON Data

   • NPC conversations, metadata, books, and book images:
     • /data/npcs/npc_transcript_database.json
     • /data/npcs/npc_metadata.json
     • /data/npcs/npc_verification_mapping
     • /data/books/book_database.json
     • /data/books/book_image_mapping.json

2. Images

   • NPC, book, spell, and creature images, padded to square in .png format:
     • /images/npcs/
     • /images/books/
     • /images/spells/
     • /images/creatures/

Example: https://resources.talesoftibia.com/images/npcs/Planestrider.png

Hotkey Mania: Detailed Guide

What is Hotkey Mania?

Hotkey Mania is a custom-made hotkey preset designed to efficiently find hidden single-word keywords when interacting with NPCs in Tibia. It's a powerful tool for documenting NPC responses and uncovering hidden transcripts. With it I've already uncovered really obscure and hidden keywords, even a new source of holy water, and documented close to 500 NPCs. A lot of really strange and interesting things have been found.

You can use it to get first look into unseen content, potentially impactful for the lore and mysteries, it's addictive and fun.

See it in action (41s):
Watch it on YouTube

What:

• Contains strings of unique words with a maximum of 255 characters each.
• Populates Action-Bar buttons for quick clicking.
• Three hotkey presets: "NPC1", "NPC2", and "NPC3".
• Includes deliberately duplicated words spread randomly across buttons.
• A bit over 1000 buttons in total.

Content of the hotkey presets:

1. 15,000 words that NPCs respond to and answer with.
2. 10,000 most commonly used English words.
3. 15,000 words