sanctuary/Farming/canaplia/docs/hemp_effect_system.md

Hemp Effect System

Goal

Each hemp variety applies:

1. a main gameplay profile,
2. a subtle visual profile during the normal trip,
3. a possible bad trip with stronger visual disturbance.

Normal trip must stay readable and non-invasive. Bad trip is the only state allowed to become truly disturbing.

---

Core rules

Consumption flow

When the player consumes a hemp item:

1. Resolve the consumed variety from its id.
2. Apply all main_effects immediately.
3. Enable the normal_visual_profile.
4. Roll one bad trip chance using bad_trip_chance.
5. If the roll succeeds, schedule the bad trip after a random delay in bad_trip_delay_sec.
6. When the delay expires, apply bad_trip_effects and enable bad_trip_visual_profile.
7. When the main duration ends, clear normal visuals and gameplay effects.
8. When the bad trip duration ends, clear bad trip visuals and gameplay effects.

---

Design constraints

Normal trip

Normal trip should:

• remain comfortable for 2 to 3 minutes,
• never make HUD unreadable,
• never make combat or building frustrating,
• use only light visual treatment.

Allowed normal visual changes:

• subtle tint,
• mild saturation shift,
• mild contrast shift,
• very light vignette,
• very light ghosting.

Forbidden during normal trip:

• strong blur,
• strong wobble,
• aggressive FOV change,
• strong double vision,
• strong screen shake.

Bad trip

Bad trip should:

• feel clearly worse,
• remain shorter than the main trip,
• include nausea and hunger,
• be visually more unstable.

Allowed bad trip visual changes:

• stronger tint,
• stronger vignette,
• stronger saturation shift,
• light image wobble,
• light afterimage,
• light brightness pulsing.

---

Stacking rules

Current stacking model:

• Consuming the same variety refreshes that variety's duration.
• Consuming a different variety keeps the previous gameplay effects active and adds the new variety on top.
• Main gameplay effects from several varieties can coexist at the same time.
• A new manual consumption rerolls the bad trip entirely from the latest variety.
• Passive resin aura refresh keeps extending the same variety without rerolling the bad trip every tick.
• Only one normal hemp visual profile can be active at a time: the latest active variety drives visuals.
• Only one bad trip state can be active at a time, and a reroll replaces the previous pending or active bad trip.

---

Effect conventions

Main effect duration

Main trip duration should stay between 140 and 180 seconds.

Bad trip duration

Bad trip duration should stay between 25 and 40 seconds.

Bad trip base gameplay package

All bad trips contain at least:

• Nausea
• Hunger

Rare and very rare varieties may add:

• Weakness
• Slowness
• short Blindness

Use these sparingly.

---

Data format

Each variety entry contains:

• id: stable machine id
• name_fr: display name
• rarity: common, uncommon, rare, very_rare
• color_family: readable color identity
• main_duration_sec: main trip duration
• main_effects: list of vanilla effects
• normal_visual_profile: subtle visual profile
• bad_trip_chance: float from 0.0 to 1.0
• bad_trip_delay_sec: min/max delay before bad trip starts
• bad_trip_duration_sec: bad trip duration
• bad_trip_effects: gameplay penalty package
• bad_trip_visual_profile: stronger visual profile

---

Visual profile semantics

Intensity scale

Use a 0.0 to 1.0 scale:

• 0.05 to 0.15 = subtle
• 0.20 to 0.35 = noticeable
• 0.40+ = invasive

Normal trip should usually stay in 0.08 to 0.14. Bad trip may go to 0.25 to 0.50 depending on rarity.

Suggested shader parameters

A visual profile can drive:

• tint_strength
• saturation_delta
• contrast_delta
• vignette_strength
• ghosting_strength
• wobble_strength
• pulse_strength

Not every profile needs every parameter.

---

Implementation note

The system should be data-driven:

• all plant tuning lives in JSON,
• gameplay code reads the JSON,
• visuals are picked by profile name or inline values,
• item classes should not hardcode effect logic.

This allows easy balancing without rewriting gameplay code.