feat(items): support an @<count> stack-size suffix on item references

[69Jesse]

An item field previously placed the referenced item's stack verbatim, so every stack size needed its own ITEM declaration or .snbt file. A reference may now carry an @<count> suffix (1–64) to restack it:

giveItem oak_log@8
giveItem "Magic Wand@2"
giveItem items/magic_wand.snbt@16

The referenced item is unchanged — only the stack it is placed into — so one declaration covers every size.

Language

• parseItemReferenceParts, isValidItemCount, withItemCount in language/src/items/index.ts, with count-aware resolution across all three resolver entry points. The suffix must be all digits, which keeps direct .snbt paths unambiguous.
• checkItems reports an out-of-range count as an error, and adds a hint when a stray @ survives the split.
• The printer's bare-name regex accepts @, so oak_log@8 emits unquoted.

Reserved @ in item names

@ is now rejected in an ITEM importable's name — otherwise giveItem coins@3 could mean either the item literally named coins@3 or three of coins. Enforced in both the import.json parser and the JSON schema. Display names inside an item's NBT are unaffected.

ct_module

• The capture registry recognizes a captured stack as a known item restacked, emitting name@<count> instead of a duplicate .snbt per size. Restack matching is deliberately narrower than the registry's normal edit-adoption path: only an identity match, or a cached click-action expectation that agrees, is accepted, since a wrong guess would silently point an action at an item with different click actions.
• The dependency index folds a counted reference back onto its base entry, so two stack sizes of one item cannot race to define its graph node.
• A declaration's nbt is never mutated — withItemCount always copies.

Docs

New "Stack Counts" section in docs/htsl/basic-syntax.md, cross-linked from the affected actions and conditions. Includes the note that the count cannot come from a variable, and the doubling pattern for handing out a variable amount.

One documented unknown: whether Housing's Block Type condition takes stack size into account is untested, and is marked as such in docs/htsl/conditions.md.

Tests

New ct_module/test/itemFieldContent.test.ts, additions to itemCaptureRegistry, itemDependencyIndex, itemReferences, and importjson.test.ts, plus fixtures for the suffix, an out-of-range count, and an @ in a declared name.

Test suites have not been run against this branch yet.

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Team

Run ID: 7ee91de6-7f9b-47bd-8de9-f89791e180bb

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[greptile-apps]

Greptile Summary

The PR adds @<count> item-reference suffixes across parsing, validation, resolution, capture/export, dependency tracking, printing, schemas, and documentation.

• Supports stack counts from 1 through 64 for named, vanilla, and direct-SNBT item references.
• Preserves base declarations while creating copied, restacked NBT values.
• Recognizes captured count variants without exporting duplicate item declarations.
• Reserves @ in ITEM declaration names and reports malformed or out-of-range suffixes.

Confidence Score: 5/5

The PR appears safe to merge, with no concrete blocking or independently actionable non-blocking defects identified.

Count suffixes are validated before application, base NBT remains immutable, all resolver forms preserve the requested count, and capture matching retains the existing click-action identity safeguards.

Important Files Changed

Filename	Overview
language/src/items/index.ts	Adds suffix parsing, bounds validation, immutable count application, and count-aware resolution for all reference forms.
language/src/check/passes/checkItems.ts	Diagnoses out-of-range counts and provides targeted guidance for malformed suffixes.
ct_module/src/importables/items/projectItems.ts	Builds cached counted wrappers around resolved base items without mutating declarations.
ct_module/src/importables/items/captureRegistry.ts	Adds conservative single-stack identity indexes so captured stack variants can reuse known declarations.
ct_module/src/importables/items/dependencyIndex.ts	Folds counted wrappers onto base dependency nodes while leaving action-text differences visible.
ct_module/src/importables/items/resolveItem.ts	Composes cached click-action data onto counted NBT so click-action items retain the requested stack size.
language/src/htsl/print/helpers.ts	Allows count-bearing item references to print as lexer-compatible bare names.
language/src/importjson/parse/arguments.ts	Rejects ambiguous @ characters in ITEM declaration names with a targeted diagnostic.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
    A[Item reference text] --> B[Split optional @count suffix]
    B --> C{Resolve base reference}
    C --> D[Named ITEM]
    C --> E[Vanilla item]
    C --> F[Direct SNBT path]
    D --> G[Copy NBT and set Count]
    E --> G
    F --> G
    G --> H[Place or compare item stack]
    I[Captured Housing stack] --> J[Restack to one for identity matching]
    J --> K{Known base item?}
    K -->|Yes| L[Emit base@count]
    K -->|No| M[Export separate SNBT item]

Loading

_{Reviews (1): Last reviewed commit: "feat(items): support an @<count> stack-s..." | Re-trigger Greptile}