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 usingsetfenv(1, Gromissingcrafts)that prevents global namespace pollution while maintaining access to WoW API- Every
.luafile must begin withsetfenv(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 theGromissingcraftsDatabaseSavedVariable directly (no AceDB) via a small get-or-create helper that auto-vivifiesglobal.realmToNameToCharacter[realm][name]with default fieldsCharacter.lua: Domain model representing a character with profession knowledge and skill level checkingCharacterRepository.lua: Data access layer for character CRUD operationsCraftRepository.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. HooksMovePanelToLeft/MovePanelToCentervia the localhookGlobalFunctionhelper (seeui/Tools.lua) — not the nativehooksecurefunc, which isn't reliably present on true-1.12-era clientswindow/Window.lua: Main window — a plainCreateFrame("Frame", ..., UIParent)with aDialogBoxbackdrop, 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 independentlyfilters/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-builtEditBox, no templatelist/CraftsList.lua: Not a nativeScrollFrame+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 ownFauxScrollFrame-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 upstreamTooltipEnhancer.lua: Enhances item tooltips with recipe learning status for each character (viaLibItemTooltip, which was never Ace-based)window/OpenButton.lua: Toggle button that appears on profession frames to show/hide the main windowDataStateManager.lua: State management for UI data synchronization and event coordination — tracks current character/profession/search query and re-queriesCraftRepositoryon changeVanillaFramePool.lua: Efficient frame reuse system for performance optimizationwindow/PlacementPolicy.lua: Geometry/anchor rules per profession-frame type (now relative offsets from the profession frame'sTOPRIGHT, not absolute screen coordinates), including pfUI detection (IsAddOnLoaded("pfUI"))
Localization (src/locale/)
Tools.lua: Minimal AceLocale-free replacement — one sharedLtable.enUS.lualoads first (see the.tocorder) and populates every key as the fallback; every other locale file only receives the live table (and thus only gets to override keys) whenGetLocale()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.dumpwalks 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 growlib/LibCrafts-1.0/Professions/Turtle/Survival.luawith 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/ItemRefTooltipmethods directly)
Removed entirely
- AceAddon-3.0, AceDB-3.0, AceGUI-3.0, AceHook-3.0, AceLocale-3.0 — see
README.mdand 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
selfparameters - 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:
LibStub+ the three data librariessrc/Environment.lua,src/Compatibility.lua- Database layer files
- Locale files —
enUS.luamust stay first among locale files (seelocale/Tools.lua) - UI component files
src/DevTools.luasrc/Gromissingcrafts.lua— main addon bootstrap (plainADDON_LOADEDevent 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, thenUIPanelButtonTemplate, thenInputBoxTemplate. Build interactive widgets from bareCreateFrame+ manual backdrop/textures instead (seeDropdownhistory,SearchField.lua,OpenButton.lua). - Set
SetFrameStrataexplicitly 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+SetScrollChilddid not reliably clip its content on this client, template or no template.CraftsList.luauses 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.