Files
2026-08-07 15:43:47 -06:00

9.5 KiB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Gromissingcrafts is a World of Warcraft Classic (Turtle WoW/OctoWoW) addon that helps players track crafting recipes they haven't learned yet on their current character. It is a from-scratch, Ace3-free rebuild of MissingCrafts, built because Turtle-style 1.12 clients frequently break when multiple addons each bundle their own copy of Ace3 (AceAddon/AceDB/AceGUI/AceHook/AceLocale share a single global registry, so mismatched versions/instances taint or clobber each other). Everything here is built on native CreateFrame + manual scripting, with no Blizzard UI templates and no Ace3.

Architecture

Environment Layer

  • src/Environment.lua: Creates an isolated global environment using setfenv(1, Gromissingcrafts) that prevents global namespace pollution while maintaining access to WoW API
  • Every .lua file must begin with setfenv(1, Gromissingcrafts) to work within this isolated environment
  • Provides utility functions: erase() for table cleanup, tpop() for safe key removal

Database Layer (src/db/)

Repository pattern implementation with clean domain models:

  • Database.lua: Manages the GromissingcraftsDatabase SavedVariable directly (no AceDB) via a small get-or-create helper that auto-vivifies global.realmToNameToCharacter[realm][name] with default fields
  • Character.lua: Domain model representing a character with profession knowledge and skill level checking
  • CharacterRepository.lua: Data access layer for character CRUD operations
  • CraftRepository.lua: Complex repository finding missing recipes based on character filters, handles craft sources mapping

UI Layer (src/ui/)

Native-frame component system, no widget framework, and no Blizzard UI templates on anything interactive (UIDropDownMenuTemplate, UIPanelButtonTemplate, InputBoxTemplate, UIPanelScrollFrameTemplate were all tried and all got their input handling broken by pfUI's skinning — see git history). Every interactive frame is hand-built (manual backdrop/textures) and every one of them sets SetFrameStrata("DIALOG") explicitly, because strata is not inherited from a parent frame on this client — leaving it unset was silently losing click priority to whatever else was on screen underneath.

  • UIManager.lua: Central coordinator managing window lifecycle, profession frame events, and component interactions. Hooks MovePanelToLeft/MovePanelToCenter via the local hookGlobalFunction helper (see ui/Tools.lua) — not the native hooksecurefunc, which isn't reliably present on true-1.12-era clients
  • window/Window.lua: Main window — a plain CreateFrame("Frame", ..., UIParent) with a DialogBox backdrop, fixed "DIALOG" strata, anchored directly to the profession frame (SetPoint("TOPLEFT", professionFrame.widget, "TOPRIGHT", ...)) so it moves with it automatically via WoW's native anchor propagation — no drag support of its own, not meant to be repositioned independently
  • filters/FiltersPanel.lua: Plain frame holding just a search box (the profession/character dropdown filters were removed by request — the window is already scoped to whichever profession frame it's attached to, and always the current character)
  • filters/SearchField.lua: Hand-built EditBox, no template
  • list/CraftsList.lua: Not a native ScrollFrame + SetScrollChild — that combination wasn't clipping its content reliably on this client (rows kept spilling past the frame's own height regardless of template). Instead it's a fixed pool of row widgets sized to exactly fill the visible area (the same technique Blizzard's own FauxScrollFrame-based lists use), with a scroll offset into the data. The scrollbar (bigger than Blizzard's default, click-and-drag capable) is fully custom too, built the same template-free way.
  • list/CraftsListItem.lua: Individual recipe row — always was plain frames, unchanged from upstream
  • TooltipEnhancer.lua: Enhances item tooltips with recipe learning status for each character (via LibItemTooltip, which was never Ace-based)
  • window/OpenButton.lua: Toggle button that appears on profession frames to show/hide the main window
  • DataStateManager.lua: State management for UI data synchronization and event coordination — tracks current character/profession/search query and re-queries CraftRepository on change
  • VanillaFramePool.lua: Efficient frame reuse system for performance optimization
  • window/PlacementPolicy.lua: Geometry/anchor rules per profession-frame type (now relative offsets from the profession frame's TOPRIGHT, not absolute screen coordinates), including pfUI detection (IsAddOnLoaded("pfUI"))

Localization (src/locale/)

  • Tools.lua: Minimal AceLocale-free replacement — one shared L table. enUS.lua loads first (see the .toc order) and populates every key as the fallback; every other locale file only receives the live table (and thus only gets to override keys) when GetLocale() matches its own code
  • Multiple language files (enUS, ruRU, deDE, frFR, esES, ptBR, koKR, zhCN, zhTW)

Dev tooling

  • src/DevTools.lua: /gromissingcrafts (alias /gmc) slash command. dump walks whichever trade skill/craft window is open (GetTradeSkillInfo/GetCraftInfo + item-link parsing) and prints each recipe's exact name and result item id, since neither spell id nor required skill level is exposed by the client API for known recipes. Used to grow lib/LibCrafts-1.0/Professions/Turtle/Survival.lua with confirmed data instead of guesses.

Key Technical Features

Event-Driven Architecture

  • Uses LibCraftingProfessions events (LCP_SKILLS_UPDATE, LCP_FRAME_SHOW, LCP_FRAME_CLOSE) for real-time updates
  • Automatic profession data synchronization when skills are learned
  • Dynamic UI updates when profession frames open/close

Data Persistence

  • Cross-realm character data storage with automatic cleanup, stored directly in GromissingcraftsDatabase
  • Profession knowledge tracking with skill level requirements
  • Recipe source mapping from LibCrafts constants to internal enums

External Dependencies

Kept from MissingCrafts (none of these were ever Ace3-dependent)

  • LibStub: tiny library-versioning shim, not part of the Ace3 conflict surface
  • LibCraftingProfessions-1.0: Profession frame detection and skill tracking across multiple addon types (extended here with Survival)
  • LibCrafts-1.0: Comprehensive crafting recipe database with source information (extended here with Professions/Turtle/Survival.lua)
  • LibItemTooltip-1.0: Tooltip enhancement framework (hooks GameTooltip/ItemRefTooltip methods directly)

Removed entirely

  • AceAddon-3.0, AceDB-3.0, AceGUI-3.0, AceHook-3.0, AceLocale-3.0 — see README.md and the plan history for the replacement mapping

Supported Profession Addons

  • Default WoW profession frames
  • AdvancedTradeSkillWindow (ATSW)
  • AdvancedTradeSkillWindow2 (ATSW2)
  • Artisan
  • pfUI

Different frame types require different initialization delays and positioning strategies — see PlacementPolicy.lua.

Development Guidelines

Code Style

  • Extensive use of Lua ---@ type annotations for documentation and IDE support
  • Object-oriented patterns using metatables with self parameters
  • Acquire/release pattern for UI components to prevent memory leaks
  • Repository pattern for clean data access abstraction

File Loading Order

Files must load in the order given in Gromissingcrafts.toc:

  1. LibStub + the three data libraries
  2. src/Environment.lua, src/Compatibility.lua
  3. Database layer files
  4. Locale files — enUS.lua must stay first among locale files (see locale/Tools.lua)
  5. UI component files
  6. src/DevTools.lua
  7. src/Gromissingcrafts.lua — main addon bootstrap (plain ADDON_LOADED event frame, no AceAddon)

No live-client testing available in this environment

Changes here are verified statically (Lua syntax checks, manual trace-throughs, cross-checking renamed globals). Real acceptance testing has to happen in-game on OctoWoW/Turtle WoW.

Lessons learned the hard way (read before touching UI code)

  • No Blizzard UI templates on interactive frames. pfUI (and likely other skinning addons) hook/reskin recognized templates and this repeatedly broke click handling for dynamically-created widgets — first UIDropDownMenuTemplate, then UIPanelButtonTemplate, then InputBoxTemplate. Build interactive widgets from bare CreateFrame + manual backdrop/textures instead (see Dropdown history, SearchField.lua, OpenButton.lua).
  • Set SetFrameStrata explicitly on every interactive frame, not just the top-level window. It is not inherited from a parent in this client; an unset child silently defaults to "MEDIUM" and can lose click priority to something else on screen even while it visually renders on top.
  • Native ScrollFrame + SetScrollChild did not reliably clip its content on this client, template or no template. CraftsList.lua uses a fixed-size row pool instead (see that file's header comment).
  • Anchor to the frame you want to track, not to a computed absolute position. The window used to snapshot the profession frame's screen coordinates once and reposition on a few known hooks; now it's anchored directly via SetPoint(..., professionFrame.widget, ...) so it tracks automatically, including drags, with no extra code.