Weapon Completeness Standard - Herbertofury/Advent-of-Ascension GitHub Wiki

Complete Weapon Standard

Every weapon is a complete experience, not just a mesh. This is the mandatory design, implementation and QA contract for the AoA weapon upgrade. All 31 feature groups apply to every weapon review. The full artwork program covers 434 audited raw release-union IDs, including 411 first-target IDs. The older 228-firearm implementation register is a subset, not the full weapon roster. Shared art never merges distinct registry IDs.

1. The package each weapon must receive

Identity, concept and construction

Exact-version original appearance, function, stats, resource, projectile, effects and acquisition route.
Canonical concept sheet, side/front/top views, material/texture direction and original-versus-upgraded comparison.
Accurate silhouette, proportions, grip, hand room, visible supply-to-emitter story and moving-part clearances.
Original UV/textures with purposeful pixel shading, material separation, edges, wear, seams and emissive detail. Study actual TaCZ pack files, not only promotional pictures.
Separate concept sheets and acceptance for craftable alternate designs. An interesting alternate cannot silently replace the canonical concept.

Complete firing and effect package

Projectile designs and in-flight behavior; alternate projectile concepts and actual resulting values.
Tracers and trails, including taper, lifetime, color, motion and customization.
Muzzle flash, smoke, sparks, local light, recoil and sound synchronization.
Entity/armor/terrain/fluid impacts and any separate area-effect behavior.
Surface decals: marks, scorch, magical imprints, alignment, fade and bounded cleanup.
Death/kill/finisher concepts, storyboards, sounds and selectable effects, triggered only by valid confirmed outcomes.
Configurable projectile, tracer, muzzle, impact, decal and finisher channels. Cosmetics must not secretly change damage or resource use.
Show original projectiles and impacts alongside new concepts. Label real game captures, extracted assets, concepts and offline renders accurately.

Crafting and the modular armory

Recipes, materials, ingredient images, acquisition, loot, achievements, boss rewards and progression.
Craftable variants with clearly documented mechanical differences.
Barrels/converters, sights/scopes, receivers, grips/stocks, suppressors/brakes and appropriate fantasy equivalents.
Ammo/energy/feed modules and visible loading/resource-service stories.
Dismantling and effect salvage: donor identity, transferable effects, conflicts, stacking, balance, preview and persistence.
Original skins/mastercraft styles, earned functional charms, static/animated/glowing stickers and custom emblems.
Visible attachments, tooltip values and authoritative behavior must describe the same resolved build. More barrels can have meaningful effects when designed, but a render is not their implementation.

Complete animation and audio package

Idle, equip, holster, supported movement, sprint/crouch and aim transitions.
Firing, per-emitter recoil, charge, cooling/recovery, blocked/dry input and rapid-repeat handling.
Tactical/empty reload where appropriate, or the correct energy/resource-service animation. Reloading remains optional where the weapon's resource design calls for it; never replace Spirit/mana with generic bullets for convenience.
Inspect and playful mastercraft choreography, with safe cancellation and reduced-motion options.
Hand/prop ownership through extraction, carrying, insertion and release. No floating clips, crushed hand space, clipping triggers or impossible supply paths.
Fire/charge/handling/reload/inspect/flight/impact/finisher audio, environmental response and source/license evidence.
First-person, third-person, world-held/dropped and GUI presentation where supported.

Integration, documentation and quality

Actual pinned native-stack loading and gameplay, multiplayer authority, resource accounting, save/load/migration and optional-mod compatibility.
Effective stats, build previews, exact icons, clear tooltips and complete illustrated documentation.
Startup and frame-time/memory budgets, LODs, bounded effects/caches, no repeated scans, and accessibility controls.
Retained source files, concepts, previews, receipts, native footage and known defects.

2. Concept fidelity is a separate hard gate

A valid file, a successful parser test or a collision check does not mean the weapon looks right.

Before modeling, pin the chosen concept and its hash. Identify landmarks: receiver/core, barrel/emitter arrangement, stock, grip, guard, magazines/resource chambers, sights and ornament. Compare their relative size, spacing, curvature and material boundaries. Review the model at the same angle and in six useful views; fix the camera rather than accepting cropped or misleading comparisons.

Before claiming visual acceptance, record paired concept/model evidence and an explicit review of silhouette, proportions, negative space, grip, materials, texture density, color, animation and effects. Preserve any deliberate deviation as an approved alternate or document why a functional adjustment is needed. Do not pass a simplified look-alike merely because it shares the colors.

Owner feedback overrides a previous visual assessment. Failed or unreviewed art stays failed or unreviewed. Automated tools validate evidence and numeric constraints; they cannot certify beauty or concept fidelity.

3. Three independent phases for every feature

Each of the 31 catalogue rows records:

Concept/design: art or storyboard for visible features; a concrete specification for nonvisual systems.
Implementation: versioned source/asset and integration status.
QA: scoped evidence, defects and the tested environment.

Use not_started, in_progress, blocked, ready_for_review or passed. Never substitute a concept for implementation, or a unit test for native acceptance. Every phase needs evidence before passed.

An intentional omission requires a reason and explicit owner approval. Never default a feature to “not applicable.” An energy weapon may have resource recovery instead of a conventional magazine reload, but the entire animation/resource feature still needs a design and review.

4. Six independent acceptance gates

Mechanism continuity and exact-version behavior.
Spatial/mesh correctness, hands, attachments and swept motion.
Animation ownership, interruption and recovery.
Confirmed-shot behavior, feedback and resource consistency.
Export and resource loading in the pinned native stack.
Native gameplay, networking, saves, performance and visual review.

Check keyframes, dense samples, extrema, transitions and known-bad regression fixtures. Sampled AABB clearance is only that; it is not continuous triangle collision proof. Inspect moving parts at normal and slow speed. Keep authored defaults, optional variants and all supported attachment combinations identifiable; disclose which combinations were actually exercised.

Native hand geometry is the reference

Released TaCZ hand-render contract: the functional hand nodes delegate to the current player renderer. Example authoring cubes do not prove the final rendered arm dimensions. Test actual wide/slim variants, both main hands, the complete transform chain and first/third-person animation. Never shrink a proxy, hand or trigger simply to turn a clearance failure into a pass.

5. Performance without hiding losses

Maintain high-detail and LOD sources separately. Benchmark startup, frame times and lows, memory and effects costs in comparable native scenes. Do not call fewer triangles or smaller JSON an FPS result. Preserve resource/animation/visual correctness while optimizing. Exact float32 export equivalence is useful evidence, but it is not native rendering or loading acceptance.

6. Current owner-directed corrections

Soul Storm: current grip, proportions and weak floating-looking flame are not canonical-quality accepted. Rework toward the concept. The flame must be rooted in its socket and form a clear crosshair when focusing/aiming; retain optional candle/gem choices. Improve actual texture work with reference-pack study.
Discharge Shotgun: the supplied concept is the explicit visual target. Match it closely; include the depicted craftable variants and their effects. Concept approval is not model/runtime approval.
Iominator: preserve and improve the current looping rear-feed design as a separate craftable alternate. The canonical version must follow the supplied concept. Do not use alternate-design approval to pass canonical fidelity.

7. Definition of done

A weapon is fully accepted only when every feature has passed its concept/design, implementation and QA phases (or has an owner-approved documented omission), the canonical visual review is accepted, all six native/technical gates are passed with evidence, and its guide exposes the complete package and remaining compatibility limits. Until then, report the real milestone and open work.

The machine-readable catalogue, manifest template, coverage register and validator enforce completeness bookkeeping. They never grant native or artistic acceptance by themselves.

Reusable checklist and tools

Ten structural/evidence regression cases pass, including missing features, unapproved omissions, false completion, absent visual comparison, wrong hashes and missing native evidence. These tools enforce bookkeeping; they cannot certify artistic quality or gameplay. Existing work must be reconciled per feature, not erased or automatically promoted. The package is reusable project guidance; publication does not claim replacement of an installed personal skill.

8. Required aesthetic and play-experience self-review

At each meaningful iteration, answer these questions with evidence and specific defects, not a generic score or praise:

Would I choose to use this weapon, and what gives it a recognizable AoA identity?
Does it match the chosen concept's silhouette, proportions, negative space and material hierarchy from comparable viewpoints?
Is it beautiful at normal gameplay scale as well as in a close-up render? Is any part still toy-like, weak, floating, cluttered or awkward?
Do firing, recoil, impacts, sound and recovery make its intended power readable? Does feedback stay clear during rapid use?
Is the animation enjoyable repeatedly, with responsive input and safe interruption? Are hand clearance and the visible resource path believable within the fictional design?
Do attachments and craftable variants create distinct useful play choices, with visible and mechanical changes that agree?
Are projectile, muzzle, impact and finisher effects exciting while preserving aiming clarity, accessibility and performance?
What is the weakest part now, what concrete change addresses it, and what evidence would show the change worked?

Record observation type: concept inspection, authoring render, offline animation, or native playtest. A render can establish an art defect; it cannot establish that a weapon is fun to play. Native play-feel remains untested until actual interaction is observed. A failed answer stays a tracked defect and prevents complete acceptance where relevant. Do not increase praise to match effort spent.

For the full-set announcement, reconcile all 228 first-target IDs plus the separately inventoried historical/version-exclusive scope. Report exact version coverage, remaining unsupported combinations and evidence. Never announce every AoA weapon complete from the first-target count alone.

Reviewed per-weapon feature manifests

All 31 rows remain visible in each manifest. Evidence points to exact files by SHA-256. Both are incomplete and fail the release-complete gate as intended; source studies, concept approval and scoped tests are not complete gameplay acceptance.

9. Source-to-export regressions that must be caught

Measure the actual authoring FPS, frame hold and atlas sequence. Do not assume a default scene rate. Test the presentation sampler against the recorded timing data.
Evaluate modifiers, curves and transforms before geometry checks. Triangle area and unit-normal length do not prove outward winding. Check intended closed-solid orientation and review open surfaces/culling separately.
Detect exact duplicated surfaces; review intended overlays instead of blindly deleting them. Stress-test the actual thin-part constructors so new inlays and indicators do not repeat old bevel-collapse defects.
Compare authoring and exported material appearance using matched camera, lighting, sample count and seed. Preserve procedural coordinate meaning, raw color and emission intensity. A diffuse BSDF contribution is not automatically the intended raw metallic color.
Preserve per-part ownership through UV packing/baking. Verify positions, UVs, material mapping, corner-normal error and controlled owner motion. A merged still image cannot pass animation ownership.
Turn critical measured limits into failing tests. Logging a large normal error while returning success is not a pass.
Prioritize texel density where detail needs it before increasing every texture. Report local error regions, memory assumptions and native limits; background-heavy image averages can hide defects.
Fail unsupported material/alpha/rig cases explicitly. Do not silently apply an opaque-material pipeline to transparent flame or mixed shaders.
Compare the original pre-rig world pose with the evaluated parented neutral pose. A return-to-ready test can pass when the initial rig is already wrong. Include nonorigin parent transforms and a negative control; visually inspect missing or displaced parts. See rig-parenting regression and limits.
Keep source revisions and evidence hashes aligned. A corrected authoring scene does not repair an older exported fixture automatically.

These checks supplement concept fidelity, real hand fit, native gameplay and performance testing. They do not replace them.

Released firing-source coverage

Projectile/firing declaration study indexes the pinned classes for all 228 first-target registrations, including inherited overloads. This is source navigation, not 228 completed upgrades. A firing method name or projectile class name cannot establish all behavior; actual dispatch, impact/resource logic and native tests remain required.

Apoco Assault Rifle now has an exact-release baseline and first concept candidate, with its full feature review still open.

10. One canonical concept, two selectable visual treatments

Start with one AAA-quality canonical concept faithful to original AoA silhouette and identity, then personally author the model and textures for both Minecraft-fit and concept-faithful presentation. Both represent the same weapon and resolved build. Later attachments and craftable variants still receive their own derived art and QA.

The initial Apoco generic long-rifle concept and v1/v2 blockouts are owner-rejected history. The replacement candidate preserves the compact identity; it is not native acceptance. Color resemblance alone cannot pass the visual gate.

11. Lore before canonical concept approval

Every weapon needs a source-pinned origin and lore review covering upgrade lineage, environmental identity, confirmed statements, visual interpretations and unknowns. Lore and provenance requirements. Both visual treatments must preserve that identity. Do not invent an official maker, material or damage effect from a visual motif.

Lore-aware validator and checklist v3: 19 synthetic evidence regressions pass; unknown lore stays unknown and cannot silently become a confirmed claim. No weapon receives native or artistic acceptance from these checks.

Whole-arsenal scope reconciliation

What every weapon finished means reconciles the 228 first-target firearm registrations with the broader 412-registration historical census. Three class/family-matched rename candidates explain raw-ID differences; they are not automatically new weapons or verified save migrations. Later/earlier versions and other families still require reconciliation. Fully accepted native upgrades remain zero.

Verify the actual geometry backend

The pinned TaCZ geometry and glTF-animation contract is mandatory context for export QA. The inspected glTF manager loads animation data; its existence does not prove support for arbitrary triangle/PBR GLB meshes. A reference GLB remains an authoring asset until a real supported geometry path renders it in-game with correct hands, materials, animation and measured performance. Do not mark a gun ready by renaming files or passing only JSON/format checks.

Source art and moving-assembly checks

Updated reusable guidance package v4 preserves the v3 lore, dual-visual-treatment and 31-feature contracts. Its 19 synthetic validator cases still pass. The focused addition addresses observed production defects:

Generated recipe icons and sprite lookalikes must not masquerade as extracted source evidence.
Exact resource-ID and registry-class review prevents Boulder/Boulder Dash/Boulder Bomber confusion and guessed-subclass errors.
Shot-level boosted decisions must remain shared across the actual pellet loop.
A parser or transform pass cannot substitute for moving-mesh clearance checks. Recoil trim ownership, receiver stroke space, baseline contacts and sampling limits must be reviewed separately.

The Discharge recoil review is a concrete example: a deeper surface check found clipping despite earlier parser/transform success. The corrected sampled result remains authoring evidence, with native hands and gameplay still open. This package is published project guidance; it does not claim installation into a personal skill directory or acceptance of any weapon.

Native event identity and truthful concept captions

Reusable guidance package v5 retains the 31-feature schema and all 19 synthetic validator cases unchanged. The new focused guidance covers failures found during source audits and actual concept production:

Distinguish the conventional gun path from the energy/blaster branch before binding presentation. Soul Storm is a blaster; an arbitrary recoil/effect callback is not enough to identify a successful shot.
Reuse the confirmed-shot core's resolved emitter index. An arrival counter fails when shot ordinals have gaps.
Keep reward eligibility, pool chance, roll count and relative weights separate. Crystaneer's illustrated loot guide demonstrates those boundaries.
Inspect generated image text before publishing. A painted inspect vignette cannot be labeled in-game, and invented material names cannot become official lore.
Names and recipe ingredients do not prove projectile behavior: Red Rocket remains a shotgun in original mode; Clown Cracker's Confetti Piles do not replace Metal Slug ammo.
A noisier material is not automatically an art improvement. Preserve rejected candidates and promote only demonstrated improvements.

All 228-item native event-source audit · Conditional loot example · Corrected image-label example

The package passes skill structure validation and the existing 19-case evidence validator. Its guidance additions have not received independent behavioral evaluation or native testing. It remains project guidance, not an installed personal skill or weapon acceptance.

12. Concept-view consistency and reproducible authoring

Apply these checks when revising illustrated weapon sheets or publishing Blender-generated sources:

Check the same prop revision in the hero, side and inspection views. Sweet Tooth's revised hero retained an obsolete doubled collar in its inspection inset; a corrected hero alone did not close the sheet review. Keep old revisions labeled and correct the affected image itself.
Review hand use in the actual facing direction. In a left-facing conventional prop, a rear shooting grip belongs behind its trigger toward the stock, not in front toward the muzzle. Do not accept an open guard as sufficient if the grip arrangement still prevents a natural reach. Fantasy alternate controls need their own intentional usability explanation.
Generated labels such as “silhouette match” or a definitive origin sentence require their own evidence. Sludge Sniper's labels were changed to “design study” and “proposed art direction”; a separate caption does not make an unsupported image label valid.
Require a clean archive extraction and a failing process exit on authoring-script errors. Use Blender's --python-exit-code option. The optional-sight scene saved before a later manifest-writing error; its existence was not evidence of a successful build. Preserve geometry checks separately from packaging checks.
Scripted custom-property changes may leave stale evaluated visibility until the dependency graph is tagged. Test the exact helper used to switch variants, including viewport and render visibility, rather than testing only manually scrubbed frames.
Audit bundled helper-library semantics before naming effect levels. EffectsLib 1.7's builder subtracts one from its level before constructing Minecraft's amplifier: builder level 3 is Speed III. Sweet Tooth also buffs the shooter after successful attack, not the target or every cosmetic shot. Keep these facts pinned to the inspected release.

Evidence: Soul-Storm-Optional-Sight-Workshop, Sludge-Sniper-Weapon-Profile and Sweet-Tooth-Weapon-Profile. These examples guide scoped review; they do not certify native gameplay.

Updated reusable skill package v6. This focused instruction update retains the existing 31 feature groups and validator; no independent agent evaluation was run.

Honor source PNG alpha before judging silhouette or passing a flattened reference to art/model tools. Discarding alpha can expose hidden RGB as false geometry; render a neutral-background reference while preserving the original texture. The Discharge Sniper example demonstrates this failure mode.

Sprite transparency audit and reference workflow.

13. Refresh profile discovery without resetting review state

The earlier coverage builder merged saved rows after deriving existing_profile from the queue. Saved null links overwrote newly discovered profiles: the feature register still exposed only 13 references while the armory had more than 50. Refresh derived links after preserving previous review metadata.

Use refresh_coverage.py with explicit --queue, --coverage, --output and --receipt paths, or build_standard.py --docs. The helper rejects duplicate IDs, inventory/family drift and invalid profile URLs. Missing queue metadata does not erase an older reference. It changes only existing_profile, retaining manifests, statuses, overrides and unknown extension data. Replaced links remain in its receipt.

Nine tests cover preservation, replacement receipts, missing metadata, idempotence and rejected inconsistent inputs. The full builder output is compared with the helper's expected result. This repairs discoverability only; a linked profile is not proof that any feature or native gate has passed.

Reusable skill package v7 includes the corrected builder and link-refresh helper. Refresh receipt.

14. Discover existing feature reviews without changing their status

Existing Soul Storm and Discharge Shotgun review files were present but not linked from the coverage index. The discovery pass now resolves actual per-weapon manifests by registry ID and target, preserves every review state and rejects conflicting or duplicate records. Sabbath’s new concept/effects record is also linked; implementation and native QA remain open.

Discovery tool and seven preservation tests · Exact pointer changes. Run this after regenerating coverage, alongside the profile-link refresh. A visible record is not a completed weapon.

15. Rebuild from current reviews, not an old archive

The v8 builder now reads the docs-side coverage register first, uses the bundled copy only as a fallback, merges missing owner-direction defaults without overwriting newer overrides, and runs both profile and feature-manifest discovery. Three end-to-end regressions exercise newer review preservation, unknown override fields and conflicting manifest rejection.

Reusable v8 skill and build/check tools. Nineteen preservation/discovery tests plus nineteen synthetic evidence-validator cases pass; no independent agent behavioral evaluation or native weapon acceptance is claimed. The skill also records the Discharge stale-transform scale bug and requires actual rebuilt visual/size review alongside parent-following tests.

A later crown-profile trial also exposed Blender object-transform decomposition: assigning an arbitrary affine shear to matrix_world did not retain the intended matrix. Its verification failed before promotion. For that specific study, a scoped local geometry/path deformation with inverse-transpose custom-normal handling preserved object transforms and parents; all 325 geometry objects were checked, with only 18 intended components changed. Do not generalize a successful static deformation into validated animation or export. Check hierarchy order, evaluated geometry and the resulting render.

16. Current package: inheritance, precision and reproducibility

The canonical reusable package now contains the current preservation-aware tools and source register, plus the observed projectile-inheritance, thin-triangle precision and portable build-chain checks. Older versioned packages remain historical references. This refresh changes guidance and discovered evidence links, not weapon acceptance.

Do not copy a neighboring weapon’s gravity: Ghoul Cannon’s 0.05 differs from Flower Cannon’s 0.1, and inherited methods matter. Test numerical geometry checks against unchanged source before interpreting small discrepancies as real deformation. Package from an obtainable pinned source and reproduce intermediates within the build rather than requiring an unavailable intermediate file hash.

The skill structure validates; nineteen preservation/discovery tests and nineteen synthetic evidence cases pass. These tests do not certify beauty, native performance or completed gameplay.

17. Version-specific fluid effects and delayed world cleanup

Water Balloon Bomber demonstrates why newer source is not an automatic semantic replacement. The inspected 1.20.1 implementation searches downward for water placement using a literal Y=0 boundary. The refreshed 1.21 source instead places temporary water at the explosion position and schedules a write of air after 20 ticks. Preserve the selected version contract and explicitly decide any migration; visual improvements must not silently change persistent fluids, placement or damage.

Before adopting a delayed world edit, test another player/mod replacing the block before cleanup, overlapping effects, protected destinations, fluid propagation and chunk/dimension unload or reload. Removal must be conditioned on ownership of the still-current effect, not merely a coordinate remembered earlier. Matching block type alone may miss a replacement with an identical state. The observed newer callback has no same-state/ownership condition of its own; this is a source-level risk to test, not a reproduced native loss report or a completed fix.

Evidence: Water-Balloon-Bomber-Weapon-Profile and its separately pinned version-comparison record. Check the actual destination, not only the original impact position. Keep negative-height behavior explicit instead of assuming every dimension starts at zero.

18. Keep authoring downloads available without bloating the website

For this repository's Jekyll deployment, packaged authoring ZIPs are retained in the repository and listed in docs/_config.yml exclusions. Known download links point to repository-hosted files. Interactive models, browsing thumbnails and data remain in the site. Full-resolution concept files stay unchanged in the repository; the armory loads them on demand through a fixed repository origin. When adding a concept, check its routing, the Jekyll exclusion list and test-armory-image-delivery.cjs. A smaller deployment must not mean resampling or deleting the original art. When adding an archive, review its deployment routing and update the exclusion list if appropriate; do not delete source archives or original concept versions to make the site smaller.

Validate changed links and preserved bytes, then check the actual deployment and a representative download. The October 20 delivery change excluded 141 intact archives totaling 197,031,164 bytes; the observed Pages artifact fell from an earlier 888 MB to 706 MB. These are delivery measurements, not native FPS or page-load benchmark claims. GitHub Pages currently limits published site size to 1 GB; keep headroom for the remaining arsenal rather than duplicating every downloadable source bundle into the site.

Dedicated customization artwork for every identity

The full customization art program and 434-ID register extend the same 31-feature contract to every audited weapon family. Each identity has 14 dedicated sheet groups: sights; barrels/muzzles/converters; feed/resources; grips/stocks/supports; skins; stickers/emblems; charms; projectiles/tracers; muzzle/charge feedback; impacts/decals; finishers; animation; complete builds/crafting/UI; audio/accessibility.

No category is silently omitted. Use an identity-appropriate equivalent or an explicitly approved exception. Existing evidence is preserved and reconciled rather than reset. Partial candidate art is not an accepted complete package. Base artwork coverage is complete for the current audited roster, but no customization package or native implementation is accepted by this register.

Optional effects and functional conversions remain separate. A visual effect does not authorize a damage, ammo, targeting or terrain-destruction change. Test native results with AoA and TaCZ together.