MCSkylines-Narcotics

Configuration defaults: Values shown for operator-configurable settings are the bundled defaults, and can be changed in the module’s configuration or definitions. The server’s active settings take precedence, so costs, speeds, ranges, durations, chances, effects, recipes, limits and enabled features may differ. Command examples illustrate syntax; fixed mechanics and validation bounds are not configuration defaults.

Narcotics is a configurable fictional substance engine with consumption routes, effects, persistent dependence, withdrawal, driving impairment, fermentation quality and durable tools. Server operators can replace all bundled names, ingredients, effects, recipes and probabilities.

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.

Water and ignition integrations

Fire now uses the registered IgnitionApi for genuine lighter ignition. Utilities exposes a water-consumption API, but Narcotics brewing does not yet require or debit grid water. Treat water-backed brewing as a future integration, not a shipped recipe requirement.

Fermentation quality and rewards

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. Fire calls this service; other ignition integrations 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].

Treatment and configuration

Authorized treatment reduces a specified addiction track by one to three levels; it is not an automatic reset of every track or a cure for all intoxication. Death clears intoxication/driving impairment and preserves dependence. Use current track keys from the status view and configuration. Health integrations treat through the registered service rather than editing Narcotics persistence. Brewing does not consume Utilities water today.

Review substances, route materials/plain paper requirement, tools/use limits, fermentation ingredient sets and ages, recipe permissions, withdrawal timing, impairment and messages in the module YAML files. Renamed items, stacked durable tools, or invalid use counts are rejected. Protect running fermentation data and tool/item IDs when changing content.

Bundled substances and tools

These are defaults, not universal server guarantees. Effect amplifiers below use player-visible levels; cooldown is the minimum time between successful doses. Each use independently rolls dependence progression on its named track. Impairment is the factor exposed to Vehicles.

The configurable tool defaults in substances.yml are 32 pipe uses, 64 lighter uses and one plain paper per snorted dose. The default Orchard Cider batch requires four apples and one sugar, ferments for at least 15 minutes, peaks at 45 minutes, becomes stale at three hours, and provides four servings. Its minimum quality is 35. Check the active recipe files before promising a batch’s value.

Bundled withdrawal schedules

These are configurable bundled defaults from addiction.profiles in config.yml. The first interval is the delay before withdrawal, followed by the recurring craving interval. Times are online time. Effects are applied when the configured withdrawal pulse occurs; they are not continuously applied for the whole interval.

The default authorized treatment reduces one dependence level and clears the current withdrawal state on success. An explicit treatment level is bounded to one through three. Treatment of one track does not erase other addictions. Operators can change these schedules in configuration.

Reading command syntax

Configuration defaults: Values shown for operator-configurable settings are the bundled defaults, and can be changed in the module’s configuration or definitions. The server’s active settings take precedence, so costs, speeds, ranges, durations, chances, effects, recipes, limits and enabled features may differ. Command examples illustrate syntax; fixed mechanics and validation bounds are not configuration defaults.

<argument> is required; [argument] is optional. Replace the placeholder, including its brackets, with your value. Choices separated by a vertical bar mean choose one. ... accepts the remaining words. Do not type quotation marks around multiword names unless the command specifically requires them. A bare command has no required arguments. Examples use sample players/IDs: substitute entries from your server and use Tab for configured IDs.

player means a username; operational actions usually require that player online. amount and price are currency values such as 25.00, unless the row specifies items, levels, or units. reason, memo, message, name, and statement accept text where supported. duration uses the module's duration format (for example 10m, 2h, or 7d); it is not a bare number of minutes unless stated. id is the exact identifier displayed by that system, not its friendly name. Permissions and ownership/state/location checks both apply.

Substance commands

Console status/treatment must name an online target. Example: /narcotics treat Alex alcohol 1 if alcohol is that server's track key. Issue substances/tools with /skylines give narcotics:<item> [player] [amount]; recipe IDs are not necessarily addiction-track IDs.

Root commands and aliases

These are the registered command entry points. The subcommand tables above describe their complete operations. Alias names use the same arguments as their root.