Skip to content

API‐&‐Addon‐Development

ZeeRaider edited this page Apr 15, 2026 · 2 revisions

API & Addon Development

SocialCredit provides a full public API designed for safe, stable integration.


Getting the API

Use the provider at runtime:

import com.example.socialcredit.api.SocialCreditAPI;
import com.example.socialcredit.api.SocialCreditProvider;

SocialCreditAPI api = SocialCreditProvider.get(); if (api == null) { return; }

Safer form:

if (!SocialCreditProvider.isAvailable()) {
return;
}
SocialCreditAPI api = SocialCreditProvider.get();

Key Capabilities

The API allows addons to:

  • Read and modify Social Credit scores
  • Access State Credits and State Department systems
  • Read and modify Heat values
  • Access aggregated player state
  • Use built-in Discord webhook functionality
  • React to system events

New in 1.6.3 / 1.6.4

SocialCreditPreChangeEvent

This event fires before a score change is applied.

It allows addons to:

  • inspect score changes
  • modify the delta
  • modify the reason
  • cancel the change entirely

If cancelled:

  • no score change occurs
  • no database write occurs
  • no side effects are triggered
  • no post-change event fires

Event Model

SocialCredit uses a two-stage event system:

Stage Event Purpose
Pre-change SocialCreditPreChangeEvent Intercept / modify / cancel
Post-change SocialCreditChangeEvent Observe committed changes

Example: Pre-Change Listener

import com.example.socialcredit.api.event.SocialCreditPreChangeEvent;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;

public class ExamplePreChangeListener implements Listener {

@EventHandler
public void onPreChange(SocialCreditPreChangeEvent event) {

    // Cap large penalties
    if (event.getDelta() < -10) {
        event.setDelta(-10);
    }

    // Cancel specific reason
    if ("Forbidden action".equalsIgnoreCase(event.getReason())) {
        event.setCancelled(true);
    }
}

}


Example: Basic API Usage

import com.example.socialcredit.api.SocialCreditAPI;
import com.example.socialcredit.api.SocialCreditProvider;
import com.example.socialcredit.api.result.ScoreChangeResult;

ScoreChangeResult result = SocialCreditProvider.get().addScore( player.getUniqueId(), player.getName(), 5, "Civic contribution" );

if (result.success()) { player.sendMessage("New score: " + result.newScore()); }


Important Rules

  • Do not use internal classes
  • Do not access the database directly
  • Always use the API layer
  • Treat SocialCredit as a dependency, not something to modify

Addon Philosophy

SocialCredit is designed to be extended via addons.

Examples:

  • SocialCreditFarming
  • SocialCreditBlackMarket
  • SocialCreditCivilOrder

Best Practices

  • Prefer events over polling
  • Keep integrations modular
  • Avoid hard dependencies unless required
  • Use the pre-change event for behavioural control
  • Use the post-change event for reactions

Documentation

Full API reference:

SocialCredit-1.6.4-API-Reference.md


Clone this wiki locally