Narcotics

Narcotics is a configuration-first substance engine for Paper 1.21.11. The bundled names are fictional examples, not hardcoded mechanics. Server owners can replace every display name, material, route, effect, addiction chance, withdrawal schedule, recipe, and message.

Player loop

• EATEN substances are used directly.
• SNORTED substances consume one genuine held substance and the configured amount of plain paper from inventory.
• SMOKED substances require a genuine pipe and lighter. Both tools have independently configured, bounded durability.
• DRINK is reserved for alcohol and returns an empty bottle after consumption.
• Successful addiction rolls raise the configured track from minor to moderate to severe. Death clears current intoxication/impairment but never dependence.

Brewery design

Give or craft a fermentation barrel, place it, and add an exact configured ingredient set. Sneak-right-click with an empty hand to begin fermentation. After the minimum ferment time, use glass bottles to draw the configured servings. Quality rises toward the ideal age and falls toward the stale age. Effects marked with the optional :QUALITY modifier scale from 50% duration at quality 0 to 100% at quality 100; side effects can remain fixed.

This gives alcohol an economic and gameplay purpose: skilled brewers make longer-lasting configured buffs and can sell reliably aged batches. The default cider demonstrates LUCK as a modest reward, but production servers can use other potion effects or omit rewards entirely. Repeated drinking still carries addiction and driving risk.

Optional bridges

The plugin registers two Bukkit services:

• NarcoticsApi exposes read-only addiction status and current driving impairment.
• AddictionTreatmentApi is registered when integrations.health is enabled. A Health treatment item or surgery flow can call treat/treatCategory; this keeps Health optional and addiction persistence in one owner.
• IgnitionApi identifies genuine lighters and atomically consumes a use. A future arson plugin should call ignite(Player) instead of duplicating or trusting item names.

Vehicles discovers NarcoticsApi without a hard dependency and alters server-side control input according to the current impairment factor. No packets are fabricated or intercepted.

Security model

Custom items use namespaced persistent data, not names or lore. Durable tools also require an unstacked UUID instance and a use count within the configured maximum. Consumption is validated before mutation, interactions are main-hand/off-hand deduplicated, brewery blocks cannot be moved by pistons or destroyed by explosions, and brewery inventory access/automation is blocked by default. Database paths are confined to the plugin data directory.

Commands: /narcotics status, /narcotics treat, /narcotics reload, and /brewery help. Issue substances and tools through /skylines give narcotics:<item> [player] [amount].

Using each substance route

Every working substance must be a genuine namespaced Narcotics item. Renaming a vanilla item does not grant effects.

• EATEN: use the substance directly; one item is consumed after validation.
• SNORTED: hold and use the genuine substance while carrying the configured amount of plain paper. Both the dose and required paper are consumed on success.
• SMOKED: carry the genuine pipe and lighter with remaining uses. A successful dose consumes the substance and one use from each configured tool.
• DRINK: drink the substance; the configured bottle behavior returns an empty bottle.

Main/off-hand duplicate events are collapsed so one physical action cannot apply two doses. Death clears current intoxication and driving impairment but intentionally preserves addiction progress and withdrawal state.

Addiction and withdrawal

Each successful use rolls the substance's configured addiction chance against its addiction track. Dependence advances through minor, moderate, and severe states. Withdrawal schedules, effects, and timing come from configuration and advance under the plugin's online-time model. /narcotics status reports the player's current state; treatment requires the configured permission and integration path.

Health can treat a specific track or category only through the registered treatment bridge. Narcotics remains the owner of dependence persistence, so Health should never directly edit its database.

Brewery operation

1. Craft or issue a genuine fermentation barrel and place it where automation and explosion protection are appropriate.
2. Insert the exact configured ingredient multiset. Similar-looking custom items are not interchangeable.
3. Sneak-right-click the barrel with an empty hand to start fermentation.
4. Wait at least the recipe's minimum age. Drawing early is rejected.
5. Use glass bottles to draw the configured number of servings.

Quality climbs toward the ideal age and then declines toward stale age. Effects marked QUALITY scale their duration from 50% at quality 0 to 100% at quality 100. Fixed side effects do not have to scale. Pistons, explosions, hoppers, and unauthorized inventory access are blocked according to the security policy so a running batch cannot be duplicated through automation.

Durable tools

Pipes and lighters carry a server-authoritative unstacked instance UUID and bounded remaining-use count. Duplicating names or lore does not duplicate a valid tool. The public ignition service consumes lighter use atomically for another suite plugin; callers should use that service rather than editing item metadata.

Narcotics testing checklist

1. Issue every configured substance and test its route with correct and missing prerequisites.
2. Exhaust a pipe and lighter and verify invalid, stacked, renamed, or over-max-use tools are rejected.
3. Trigger each addiction stage, die while intoxicated, and confirm dependence persists while impairment clears.
4. Test the complete withdrawal schedule using online and offline time.
5. Ferment each configured recipe, draw before minimum age, at ideal age, and near stale age, and compare quality-scaled effects.
6. Attempt piston movement, explosion destruction, hopper automation, and unauthorized barrel access.
7. With Health installed, test treatment success and the disabled-integration case.
8. With Vehicles installed, compare control behavior at multiple impairment factors.