shenandshen
c93894313a
- item_tooltip_view.gd: 新增 avoid_rect 属性，tooltip 与装备窗口重叠时自动推到左侧 - inventory_ui.gd: 悬停装备时传入窗口矩形作为避让区域 - 包含其他累积的功能开发和测试文件
116 lines
9.6 KiB
Markdown
116 lines
9.6 KiB
Markdown
---
|
|
name: metin2-40250-parity-audit
|
|
description: Audit, implement, fix, or verify behavioral parity between the Metin2 40250 Windows C++ client and this Godot client. Use whenever a request mentions 40250 comparison, 1:1 parity, missing original-client behavior, parity regressions, or continuing the client audit. Do not use for unrelated features that have no 40250 compatibility requirement.
|
|
---
|
|
|
|
# Metin2 40250 parity audit
|
|
|
|
Treat the reachable 40250 implementation semantics and its observable behavior as the reference contract. The Godot architecture and APIs may differ, but its gameplay algorithms, branch conditions, state-transition order, constants, units, timing/event sources, resource/data sources, protocol side effects, and failure/cleanup behavior must not differ unless the difference is a documented platform adapter with evidence of semantic equivalence. Compare complete call chains, not filenames or similarly named functions.
|
|
|
|
## Persistent state
|
|
|
|
The audit ledger is the source of truth:
|
|
|
|
- `audit/manifest.json`: current contract states and evidence links.
|
|
- `audit/history.jsonl`: append-only state-change history.
|
|
- `audit/contracts/`: detailed evidence for individual contracts.
|
|
- `audit/reports/`: generated summaries; never treat these as the source of truth.
|
|
- `audit/remediation-roadmap.md`: current repair order, anti-repeat rules, and the next primary contract.
|
|
|
|
Before auditing, fixing, or claiming parity:
|
|
|
|
1. Run `python3 .agents/skills/metin2-40250-parity-audit/scripts/audit_ledger.py refresh --write`.
|
|
2. Run `python3 .agents/skills/metin2-40250-parity-audit/scripts/audit_ledger.py report`.
|
|
3. Read the relevant existing contract and tests. Do not repeat a still-valid `TEST_VERIFIED` audit unless the user explicitly requests revalidation.
|
|
4. If no contract exists, add one with a stable behavior ID before marking work complete.
|
|
|
|
Before selecting the next repair target, read `audit/remediation-roadmap.md` and the
|
|
latest relevant history entries. Select by the documented priority and end-to-end
|
|
user flow, not by whichever local difference is easiest to patch. A contract may not
|
|
be used to repeat an already completed issue or branch. Every round must select an
|
|
explicit issue/branch ID using the roadmap's stable format and compare it with
|
|
`audit/history.jsonl` before editing. Older contract-level history entries do not
|
|
prove that every branch in that contract is complete; create the branch-level ID
|
|
when first selecting it.
|
|
The same issue/branch ID may be revisited only for a new regression, a substantive
|
|
implementation change, or new evidence that invalidates the earlier conclusion.
|
|
The same contract may be selected in a later round when a different `remaining`
|
|
branch is selected; contract IDs group behavior and are not deduplication keys. A
|
|
`PARTIAL` contract is not permission to repeat already verified work.
|
|
|
|
Read [references/audit-schema.md](references/audit-schema.md) whenever creating or changing ledger entries. Read [references/project-map.md](references/project-map.md) when locating reference code, current implementation, existing gap documents, or test runners.
|
|
|
|
## Full-client inventory gate
|
|
|
|
This skill covers the complete reachable 40250 client behavior surface, not only the first few reported bugs. Before claiming the audit is broadly complete:
|
|
|
|
1. Inventory active 40250 runtime areas across `UserInterface`, `GameLib`, `EffectLib`, `EterLib`, `EterGrnLib`, `PRTerrainLib`, `MilesLib`, `EterPack`, and `EterLocale`, then map each externally meaningful behavior to `project/`, `extension/`, `formats/`, resources, and tests.
|
|
2. Keep one stable contract ID per externally meaningful behavior, not one per source file. Group helper files under the behavior they implement, but do not omit a reachable behavior because its implementation is spread across several libraries.
|
|
3. Put every mapped behavior in `audit/manifest.json`, including behaviors not yet checked. Use `UNMAPPED` when no current implementation or reference mapping is established, `MAPPED` when both entry points are located, and `PARTIAL` when a material gap is known.
|
|
4. Record current-client-only features as `EXCLUDED` only with an explicit reason that they have no 40250 counterpart and are outside the parity target. Never silently omit them from the inventory.
|
|
5. The inventory is incomplete while any active runtime area has no contract entry. A clean test suite or a high percentage of mapped files does not waive this gate.
|
|
|
|
## Audit method
|
|
|
|
For each behavior:
|
|
|
|
1. Define the external trigger, preconditions, state transitions, outputs, timing, interruption, failure, and cleanup behavior.
|
|
2. Trace the complete reachable 40250 call chain, including resource-driven branches and compile-time feature flags.
|
|
3. Build a branch-by-branch equivalence table mapping the reference preconditions, decisions, formulas, state writes, ordering, timing sources, resource reads, outputs, and cleanup paths to the current native extension, GDScript, resources, protocol handling, and UI.
|
|
4. Classify every difference as missing, partial, wrong order, wrong value/unit, wrong algorithm, wrong timing/event source, wrong resource/data source, duplicate, platform adapter, or intentionally excluded.
|
|
5. Treat automated output equality as necessary but not sufficient: tests can miss branches, so a different algorithm cannot be approved merely because sampled outputs currently match.
|
|
6. Fix root mechanisms rather than coordinates, entity IDs, individual assets, one-off timing constants, or simplified approximations.
|
|
7. Add or strengthen an automated test that fails before the fix and covers the reference behavior. Include boundary, rejection, interruption, and cleanup paths when they materially affect the behavior.
|
|
8. Run the narrow test first, then related subsystem tests, then `git diff --check`.
|
|
9. Update the contract's implementation-equivalence matrix, manifest, fingerprints, and history in the same change. Never mark `STATIC_VERIFIED` or `TEST_VERIFIED` without complete equivalence evidence.
|
|
|
|
For classic network phase audits, run `scripts/audit_packet_registry.py` together
|
|
with `scripts/audit_phase_dispatch.py`. The former compares registered wire
|
|
header values and static/dynamic kinds; the latter compares Login/Select/Loading/
|
|
Game phase branches by numeric value while explicitly reporting transport-control
|
|
and observer-stream exclusions. A PASS from either script is structural evidence,
|
|
not proof that handler side effects are equivalent.
|
|
|
|
## Implementation-equivalence gate
|
|
|
|
Source text and engine-facing APIs do not need to be identical, but the implementation must be semantically unified with 40250. Before verification, prove all of these independently:
|
|
|
|
- identical effective preconditions and early-return rules;
|
|
- identical reachable branch structure and branch outcomes;
|
|
- equivalent algorithms and formulas, without simplified substitutes;
|
|
- identical state mutations and mutation order;
|
|
- identical constants, tolerances, coordinate conversions, and units after explicit platform conversion;
|
|
- identical timing authority and event source, such as `.msa` events rather than replacement timers;
|
|
- identical resource, table, and protocol data authority rather than hardcoded substitutes;
|
|
- identical network and externally visible side effects and their ordering;
|
|
- identical interruption, rejection, rollback, failure, and cleanup behavior.
|
|
|
|
Permitted differences are limited to documented platform adapters such as C++ containers to Godot collections, DirectX matrices to `Transform3D`, or Windows input APIs to Godot input APIs. For every adapter, document both sides, the conversion invariant, and a focused equivalence test. If any material item differs or lacks proof, status must remain `PARTIAL` or `MAPPED`.
|
|
|
|
## Evidence rules
|
|
|
|
- `MAPPED` means only that both sides were located.
|
|
- `STATIC_VERIFIED` requires a documented call-chain and implementation-equivalence matrix covering every material branch. Similar output alone is insufficient.
|
|
- `TEST_VERIFIED` additionally requires meaningful automated behavior tests with a recorded passing result; tests do not waive the implementation-equivalence gate.
|
|
- Engine/platform replacement may be `EXCLUDED` only when the replacement and externally observable verification are documented.
|
|
- A source or test fingerprint change makes prior verification `STALE`; investigate only the affected contracts.
|
|
- Existing prose in `docs/CLIENT-GAP.md` and similar documents is useful evidence, but it is not a current verification state unless represented in the ledger.
|
|
- Do not claim that code inspection proves visual, timing, input-feel, driver, or Windows-specific parity. Record those limits explicitly.
|
|
|
|
## Scope and safety
|
|
|
|
- Preserve unrelated dirty-worktree changes.
|
|
- Prefer the active files from the 40250 Visual Studio build; do not audit disabled, third-party, or obsolete code as product behavior without evidence that it is reachable.
|
|
- Keep credentials, live-server data, copyrighted binary dependencies, generated captures, and local run outputs out of the ledger.
|
|
- Do not change live servers or external systems unless the user requested it.
|
|
|
|
## Completion report
|
|
|
|
Report the contract IDs changed, reference and implementation call chains, discrepancies fixed, tests run, remaining unverified branches, and resulting ledger status. A subsystem is complete only when its in-scope contracts have no unexplained `UNMAPPED`, `PARTIAL`, `STALE`, or `REGRESSION` entries.
|
|
|
|
Also report whether the round followed `audit/remediation-roadmap.md`, the selected
|
|
issue/branch ID, why it was not already completed in `audit/history.jsonl`, and the
|
|
next priority candidate. Do not claim that a single subsystem is complete merely
|
|
because its focused tests pass while its ledger contract still has material
|
|
`remaining` branches.
|