Credits System

BinktermPHP includes an integrated credits economy that rewards user participation and allows charging for certain actions. Credits can be used to encourage quality content, manage resource usage, and gamify the BBS experience.

Sysop? See Credit Economy Setup for a guide on designing a balanced economy, tuning rewards and costs, and monetization considerations. This document covers the developer API and internals.

Key Features

• Configurable credit costs and rewards for various activities
• Daily login bonuses to encourage regular participation
• New user approval bonuses to welcome approved members
• Bonus rewards for longer, higher-quality content
• Transaction history and balance tracking

Default Credit Values

Activity	Amount	Type	Notes
Daily Login	+25	Reward	Awarded once per day after 5-minute delay
New User Approval	+100	Bonus	One-time reward when account is approved
Netmail Sent	-5	Cost	Private messages to other users
Echomail Posted	+3	Reward	Public forum posts
Echomail Posted (approx. 2 paragraphs)	+6	Bonus	2× reward for substantial posts (2+ paragraphs)
Crashmail Sent	-10	Cost	Direct delivery bypassing uplink
Poll Creation	-15	Cost	Creating a new poll in voting booth
File Upload	0	Cost	Optional charge applied before a file upload
File Upload	0	Reward	Optional reward applied after a successful upload
File Download	0	Cost	Optional charge applied before a file download
File Download	0	Reward	Optional reward applied after a successful download
AI Usage	0	Cost	Credits per $0.001 of AI provider spend (configurable rate)

Configuration

Credits are configured in config/bbs.json under the credits section. All values are customizable:

{
  "credits": {
    "enabled": true,
    "symbol": "CR",
    "daily_amount": 25,
    "daily_login_delay_minutes": 5,
    "approval_bonus": 100,
    "netmail_cost": 1,
    "echomail_reward": 5,
    "crashmail_cost": 10,
    "poll_creation_cost": 15,
    "file_upload_cost": 0,
    "file_upload_reward": 0,
    "file_download_cost": 0,
    "file_download_reward": 0,
    "ai_credits_per_milli_usd": 0
  }
}

Settings can also be modified through the web interface at Admin → BBS Settings → Credits System Configuration.

Transaction Types

• payment — User paid for a service
• system_reward — Automatic reward for activity
• daily_login — Daily login bonus
• admin_adjustment — Manual admin modification
• npc_transaction — Transaction with system/game
• refund — Credit refund

Developer API

Extensions and WebDoors can integrate with the credits system:

// Get user's balance
$balance = UserCredit::getBalance($userId);

// Award credits
UserCredit::credit($userId, 10, 'Completed quest', null, UserCredit::TYPE_SYSTEM_REWARD);

// Charge credits
UserCredit::debit($userId, 5, 'Used service', null, UserCredit::TYPE_PAYMENT);

// Get configurable costs/rewards
$cost = UserCredit::getCreditCost('action_name', $defaultValue);
$reward = UserCredit::getRewardAmount('action_name', $defaultValue);

Disabling Credits

Set "enabled": false in the credits configuration to disable the entire system. When disabled, all credit-related functionality is hidden and no transactions are recorded.

---

Developer: Adding a New Credit Type

When adding a new UserCredit credit or debit type, update all five of these locations:

1. src/UserCredit.php — add the new type with a fallback value to the $defaults array in getCreditsConfig(), and add validation in the $merged array processing.
2. bbs.json.example — add to the credits section with a comment explaining the type.
3. templates/admin/bbs_settings.twig — add a form field in the Credits section, load it in loadBbsSettings(), validate in saveBbsCredits(), and include it in the config object sent to the API.
4. routes/admin-routes.php — in the POST /admin/api/bbs-settings handler, add validation and include the field in $config['credits'] with correct type casting.
5. README.md — document the new type in the credits section.

Configuration priority (highest to lowest): data/bbs.json → bbs.json.example → code defaults in src/UserCredit.php.

Always add code defaults first so the system works even without bbs.json. When updating a template to show credit info, use the credits_enabled Twig variable to conditionally show it.

Credit Transaction Security

CRITICAL: Credit balance changes must only happen server-side. JavaScript requests business actions; the server decides whether credits are involved and performs the transaction internally.

❌ POST /api/credits/deduct   ← never expose credit endpoints to JS
✅ POST /api/webdoor/game/buy-item  ← server handles credits internally, returns new balance

JS may display the balance value returned by the server and communicate it to parent windows via postMessage. It must never calculate or request credit modifications.