Cravings System

Craving System Documentation

Overview

The craving system is a dynamic feature that simulates addiction cravings in the game. It uses a point-based system to track craving intensity and triggers various effects based on the craving level.

---

How Craving Values Work

Craving Points

• Each addiction has a craving points value that ranges from 0 to 100 (configurable in Config.CravingSystem.maxCravingPoints)

• When you first get an addiction, it starts with a random craving value between 0-50% of the maximum

• Points increase over time and when certain conditions are met

Craving Intensity

• The craving intensity is calculated as a percentage of your current craving points

• For example, if you have 75 points out of 100, your craving intensity is 75%

• This percentage determines when certain effects trigger

---

Timers and Triggers

Basic Craving Timer

• Each addiction level has a cravings.every setting (in minutes)

• This timer triggers regular craving notifications

• For example, a "Just Started" addiction might trigger every 35 minutes

Escalation System

• If you ignore cravings, they can escalate

• Each addiction level has a whenNotSatisfied threshold (usually around 75-85%)

• When your craving intensity goes above this threshold:

  • More frequent notifications occur (every 4-10 minutes)

  • Notifications become more urgent

  • May include additional effects like health damage or stress

---

Example Configuration

Here's how a typical addiction level is configured:

['Just Started'] = {
    cravingMultiplier = 1.3,  -- How fast cravings increase
    cravings = {
        every = 35,  -- Basic craving every 35 minutes
        notify = {
            messages = {
                'You feel like sipping some lean',
                'Some lean would be nice right about now',
                -- more messages...
            }
        },
        whenNotSatisfied = {
            threshold = 75,  -- Escalation starts at 75% craving
            every = 10,     -- Escalated cravings every 10 minutes
            messages = {
                'You could really use some lean right now!!',
                'You better find some lean soon!!',
                -- more urgent messages...
            }
        }
    }
}

---

How to Manage Cravings

Satisfying Cravings

• Using the addictive substance will reset craving points to 0

• This stops the escalation system

• The basic craving timer will continue to run

Ignoring Cravings

• Craving points will continue to increase

• Once they pass the threshold, you'll get more frequent and urgent notifications

• May experience negative effects like health damage or stress

Craving Multiplier

• Each addiction level has a cravingMultiplier

• Higher multipliers mean cravings increase faster

• For example, a multiplier of 1.5 means cravings increase 50% faster than normal

---

Craving Points Configuration

The system includes specific point values for different craving triggers, configured in Config.CravingSystem:

Config.CravingSystem = {
    uiUpdateInterval = 30000, -- How often to update UI in ms (30 seconds)
    maxCravingPoints = 100,  -- Maximum craving points (100%)
    cravingPoints = {
        onAddictionEffect = 2,    -- Points added when PlayAddictionEffect is triggered
        onCravingNotification = 8, -- Points added when HandleCraving (normal) is triggered
        onCravingPenalty = 15,    -- Points added when HandleCraving (escalated/penalty) is triggered
    }
}

Point Values Explained

• onAddictionEffect: Adds 2 points when addiction effects are triggered

• onCravingNotification: Adds 8 points when a normal craving notification occurs

• onCravingPenalty: Adds 15 points when an escalated/penalty craving is triggered

---

Summary

This system creates a realistic progression of addiction, where ignoring cravings leads to more severe consequences, while satisfying them provides temporary relief but maintains the addiction cycle.