Add full achievement definition and character-state editors

[fryguy503]

DO NOT MERGE UNTIL EQEmu/EQEmu#5119 has been accepted

Summary

This PR adds comprehensive achievement-system management to the PEQ Database Editor.

It introduces:

• Complete achievement definition graph authoring
• Achievement category hierarchy management
• Administrator-only character achievement inspection and repair
• Dynamic database-backed reference lookups
• Client- and server-side validation
• Fail-closed schema diagnostics
• Embedded help and authoring documentation
• PEQ-native styling and navigation integration

The branch changes 30 files with approximately 16,040 additions and 8 deletions.

Motivation

The EQEmu achievement system spans numerous related content and character-state tables. Managing those relationships directly through SQL is difficult and potentially unsafe, particularly around stable identities, selectable rewards, character history, and partially written graphs.

This editor provides a guided interface that validates and writes achievement data transactionally while protecting durable character and reward state.

Achievement Definition Management

Definition catalog

Adds a searchable, sortable, and paginated achievement catalog with filters for:

• Achievement ID, name, or description
• Enabled/disabled publication state
• Category
• Criterion event type
• Automatic or selectable reward content
• Definitions without rewards
• Configurable page size

The catalog displays aggregate category, component, criterion, reward, and restriction counts.

Full graph editor

A tabbed editor manages the complete definition graph as one unit:

• General definition fields
• Category associations
• Components and nested criteria
• Canonical reward grants
• Selectable reward sets and options
• Grant-to-option mappings
• Achievement-backed spell cast restrictions
• Client and server validation results
• Embedded authoring guidance

One submission validates and writes the entire graph transactionally. A failure rolls back the complete operation rather than leaving partially updated relationships.

General definition fields

Supports:

• Stable achievement ID
• Name and description
• Icon ID
• Achievement points
• Reward display value
• World-display flag
• Definition version
• Reset-on-version-change policy
• Enabled publication state

New definitions begin as disabled drafts.

Components and criteria

Supports component wire types:

• Types 0–2: state-bearing components
• Type 3: presentation-only components

Supports all 14 achievement criterion events:

1. Manual
2. Level
3. NPC Type Kill
4. NPC Race Kill
5. Task Complete
6. Zone Enter
7. Loot Item
8. Own Item
9. Tradeskill Success
10. Skill Value
11. Alternate Advancement
12. Achievement Complete
13. NPC Name Kill
14. Skill Cap

Supports progress modes:

• Increment
• Highest
• Set
• Boolean

Supports component behaviors:

• Required
• Optional
• Unlock
• Visibility
• Display Only
• Blocker

Event-specific controls explain the meaning of primary target, secondary target, threshold, replay behavior, and allowed progress modes.

Dynamic reference lookups

Provides bounded lookup suggestions for:

• Achievement definitions
• Achievement categories
• NPC types
• NPC races
• Tasks
• Zones
• Items
• Tradeskill recipes
• Alternate currencies
• Title sets

Valid numeric IDs can still be entered directly. Suggestions are optional and do not prevent authoring newly introduced or custom IDs.

Additional helpers include:

• Canonical EQEmu skill IDs 0–77
• Correct zero-based skill labeling
• EQ class IDs 1–16
• NPC-name canonicalization
• Unsigned FNV-1a NPC-name hash generation
• Custom NPC race ID support

Reward authoring

Supports reward types:

• Item
• Experience
• Alternate Advancement
• Copper
• Alternate Currency
• Title

Supports delivery modes:

• Automatic on completion
• Common to every selectable choice
• Selected by the player

Selectable reward authoring includes:

• Stable reward-set ID
• Prompt/title
• Enabled state
• Option IDs and ordering
• Common-to-all options
• Option flags
• Option enabled state
• Canonical grant mappings

Validation ensures every enabled selectable option contains at least one enabled mapped grant and that at least one enabled non-common choice exists.

Stable identity protection

The editor protects durable identities used by character state and reward idempotency:

• Achievement IDs are immutable after creation
• Category IDs are immutable after creation
• Persisted component identities cannot be silently replaced
• Existing reward IDs cannot be changed or adopted by another achievement
• Reward-set IDs remain stable
• Persisted reward options must be retired by disabling them rather than silently removed

New reward identities are allocated atomically when appropriate.

Safe cloning and deletion

Safe cloning:

• Creates the clone disabled
• Allocates a new achievement ID when needed
• Retains global component presentation identities
• Allocates new reward and reward-set identities
• Intentionally omits cast restrictions

Definition deletion:

• Requires exact typed confirmation
• Is blocked while another achievement depends on the definition
• Removes authored content only
• Preserves global component presentation counts
• Preserves durable character history
• Surfaces the remaining character rows as orphaned history

Category Management

Adds a category hierarchy editor supporting:

• Stable category ID
• Parent category
• Sibling sequence
• Name
• Description
• Optional client icon resource

The hierarchy view displays child counts and associated-definition counts.

Validation prevents:

• Missing parent references
• Self-parenting
• Parent/descendant cycles
• Reparenting beneath a descendant
• Deleting categories with children
• Deleting categories still associated with achievements

Failed submissions retain entered values and display field-specific errors.

Character Achievement Management

Character browser

Adds an administrator-only character browser with:

• Partial-name or exact-ID search
• Pagination
• Online/offline status
• Level and class
• Completed achievement count
• Active progress count
• Progress row count
• Cumulative progress total
• Last-login information

An administrator-only shortcut is also added to the existing player detail page.

Character achievement detail

Per-character achievement data can be filtered by:

• Achievement ID, name, or description
• Category
• Completed
• Not completed
• In progress
• Not started
• Definition-version mismatch
• Reward attention
• Pending mutation
• Orphaned history

The detail page displays:

• Durable completion rows
• Exact component progress
• Authored criteria and required counts
• Individual reward-delivery ledgers
• Selectable reward locks and status
• Pending cross-zone mutations
• Definition-version mismatches
• Missing or orphaned content references
• Ambiguous reward-delivery states

Administrative repair actions

Supports carefully gated actions for:

• Setting exact component progress
• Offline force completion
• Resetting completion and progress
• Optionally resetting reward ledgers
• Marking failed reward grants retryable
• Marking failed selectable reward delivery retryable
• Retrying blocked cross-zone mutations
• Discarding pending or blocked mutations

Safety behavior includes:

• Offline-only direct state repair
• Exact progress clamped to the authoritative required count
• Completed achievements protected from manual progress edits
• Version mismatches rejected
• Ordinary resets preserve reward ledgers by default
• Reward-ledger deletion requires separate confirmation
• Reward retry requires duplicate-delivery-risk acknowledgement
• Durably granted rewards cannot be retried
• Processing/leased mutations cannot be discarded
• Force completion does not directly grant rewards; server reconciliation remains authoritative

Orphaned history

Character state referencing a deleted or incomplete definition remains visible.

The editor reports:

• Orphan completion rows
• Orphan component progress
• Missing canonical reward definitions
• Missing reward sets
• Orphan reward-selection ledgers
• Orphan pending mutations

This evidence is never silently discarded.

Validation and Data Safety

Authorization

• Definition and category mutations require normal PEQ editor authorization
• Character achievement pages and actions require administrator authorization
• Mutation controls are hidden from unauthorized users

Request safety

Every mutation uses:

• HTTP POST
• Achievement-scoped CSRF protection
• Constant-time token comparison
• Strict unsigned-integer parsing
• Bounded strings and pagination
• Exact typed confirmation for destructive operations
• HTML escaping
• Safely encoded embedded JSON

Graph submissions are limited to:

• 2 MB JSON payload
• 100 category associations
• 1,000 components
• 2,000 criteria
• 500 rewards
• 500 cast restrictions
• 500 reward options

Database safety

• All supplied values use prepared statements
• Dynamic identifiers come only from internal allowlists
• Definition writes use InnoDB transactions and FOR UPDATE locks
• Character mutations use a per-character advisory lock, transaction, and row locks
• Failures roll back the complete operation
• Detailed diagnostics are logged server-side while safe messages are shown to editors
• Unsigned 64-bit values are preserved as decimal strings where PHP integers are insufficient

Authoritative validation

Server validation checks:

• Required fields and numeric ranges
• Stable identity retention
• Duplicate component and criterion identities
• Shared component presentation-count conflicts
• Event-specific target semantics
• Replay-safe progress modes
• Skill, class, level, and threshold ranges
• Category parent cycles
• Self and cross-achievement dependency cycles
• Conflicting class-gating criteria
• Missing references
• Cast-restriction conflicts
• Reward ownership
• Reward amount and type requirements
• Selectable option/grant mappings
• Enabled/disabled graph coherence

Immediate browser validation provides faster feedback, but server and repository validation remain authoritative.

Schema Diagnostics

The editor never creates or alters EQEmu tables automatically.

Before use, it verifies:

• Required tables and columns
• Compatible column types and unsignedness
• NOT NULL requirements
• Auto-increment requirements
• Required unique and non-unique indexes
• InnoDB transaction and row-lock support

If the schema is missing or unsafe, the editor fails closed and displays a diagnostics page instead of permitting writes.

Required content tables

• achievement_categories
• achievements
• achievement_category_associations
• achievement_components
• achievement_component_counts
• achievement_criteria
• achievement_rewards
• achievement_cast_restrictions
• achievement_reward_sets
• achievement_reward_options
• achievement_reward_option_entries

Required character-state tables

• character_data
• character_achievements
• character_achievement_progress
• character_achievement_rewards
• character_achievement_reward_selections
• character_achievement_pending_mutations

Separate content and character database connections are supported without cross-database joins.

Optional lookup tables produce warnings when unavailable but do not block unrelated authoring.

Editor Integration and UX

• Registers editor=achievements
• Adds achievement-aware breadcrumbs
• Adds a character-detail shortcut
• Places Achievements in the third World Data navigation row before Data Buckets
• Preserves the stock 900px PEQ shell
• Uses PEQ’s compact Verdana typography, gray work surfaces, square controls, black table headers, and dark-blue links
• Scopes achievement styles so they do not leak into other editor pages
• Prevents navigation wrapping and overlap

Every surfaced field includes one or more of:

• Visible help text
• Hover explanation
• Accessible label
• aria-describedby guidance
• Context-sensitive warning
• Exact confirmation instructions

The feature also includes a full authoring guide covering identities, publishing, progress modes, event semantics, rewards, skills, and NPC-name hashing.

Compatibility

• PHP 7.1 compatible
• Compatible with PEQ short-tag templates
• Native mysqli; no new package dependencies
• Supports same-database and split content/player database deployments
• No frontend build step
• No automatic schema mutation

Testing

Executed against eqemulator/peq-editor:latest with PHP 7.1.33:

Suite	Assertions
HTTP, CSRF, bounds, confirmations, and failed-input retention	25
Achievement metadata and graph validation	519
Character achievement service and schema safety	145
Race lookup and custom numeric IDs	11
Stable identity-retention guards	8
Template rendering and generated-JavaScript export	68
Legacy shell, navigation, and theme regression	21
Total	797

Additional verification:

• 622 PHP files passed PHP 7.1 syntax checks
• Generated achievement-editor JavaScript passed node --check
• Browser layout verified at 1015×768 and 1510×864
• Header, menu, content, and feature root remained centered at exactly 900px
• Navigation tabs had zero overlap
• No browser console errors were reported
• git diff --check passed

The optional read-only database integration test was not executed locally because database environment variables were unavailable. When configured, it verifies:

• Definition schema readiness
• Definition pagination and graph hydration
• Canonical selectable reward mappings
• Split-database character hydration
• Explicit empty subsets
• Orphan-state hydration

It performs no mutations.

Deployment Notes

1. Install or update the achievement SQL from the EQEmu source workspace before using the editor.
2. Deploy the PEQ editor changes.
3. Restart the editor container if the application files are image-baked or cached.
4. Hard-refresh the browser to ensure the updated scoped stylesheet is loaded.
5. Open World Data → Achievements and confirm schema diagnostics report ready.
6. Create or clone definitions as disabled drafts.
7. Resolve validation errors and review warnings.
8. Enable the definition only when ready to publish.
9. Run #reload achievements global.
10. Confirm the server accepted the new snapshot.

A failed server reload preserves the previous active achievement snapshot.

Increment definition_version when deployed semantics change incompatibly. Carefully review reset_on_version_change, because it can allow rewards to be delivered again.

Intentional Limitations

• This PR contains no SQL migration.
• The achievement schema must already be installed.
• The nested graph editor requires JavaScript.
• Character repairs are administrator-only and generally offline-only.
• Safe clones intentionally do not copy cast restrictions.
• Definition deletion intentionally preserves durable character history.
• The UI intentionally follows PEQ’s fixed-width 900px presentation rather than introducing a new responsive shell.
• Reward retry actions only change retry state; authoritative delivery remains server-owned.

Suggested Reviewer Focus

• Stable identity and retirement rules
• Reward at-most-once behavior and retry-risk handling
• Definition clone/delete semantics
• Character offline-locking requirements
• Split content/player database behavior
• Schema assumptions versus the current EQEmu achievement migrations
• Dependency/category cycle detection
• Selectable reward mapping validation
• Legacy menu and shell isolation

Checklist

• Full definition graph editor
• Category hierarchy editor
• Character achievement administration
• Field-level help and authoring guide
• CSRF and authorization enforcement
• Transactional graph writes
• Fail-closed schema diagnostics
• Split-database support
• PHP 7.1 compatibility
• Stock PEQ theme integration
• Automated unit, smoke, template, and layout coverage