Skip to content

Developer API

Jump to bottom
NadirKhoulali edited this page Jul 23, 2026 · 16 revisions

Developer API

UBS exposes a server-side Java API for NeoForge 1.21.1. API version 2.0.0 adds management surfaces for banks, shops, heists, and general server discovery while retaining the existing finance, cash, notification, and market-price methods.

Entry Points

import net.austizz.ultimatebankingsystem.api.UltimateBankingApiProvider;

var finance = UltimateBankingApiProvider.get();
var server = UltimateBankingApiProvider.server();
var banks = UltimateBankingApiProvider.banks();
var shops = UltimateBankingApiProvider.shops();
var heists = UltimateBankingApiProvider.heists();

finance.getApiVersion() returns 2.0.0.

Contract and Threading

  • Read models are records whose collection fields use defensive immutable copies.
  • API methods return empty/failed results when UBS world data is unavailable; they do not expose mutable Bank, CompoundTag, or internal service objects.
  • Mutations must run on the logical Minecraft server thread.
  • Mutations reuse UBS authorization and validation. An addon does not bypass ownership, role, cooldown, capacity, setup, or heist rules.
  • Operations that require an acting player may require that player to be online.
  • getTargets() performs live heist/world eligibility scans and therefore returns no targets when called off the server thread.
  • Monetary values use BigDecimal, dollars, or cents as stated by the method/record. Do not infer units from formatting.
  • The API is an in-process Java surface. UBS does not ship an HTTP/WebSocket admin server.

Result Types

  • ApiResult: simple finance result and resulting balance.
  • ApiTransactionResult: success/reason, transaction ID, source/destination IDs, amount, resulting balances, and reference.
  • ApiManagementResult: success plus a human-readable message for bank/shop/heist actions.
  • ApiCashResult: physical cash inventory operation result.
  • ApiItemResult: issued paper instrument and reference ID.
  • ApiNotificationResult and ApiAlertResult: UI-delivery outcomes.

Finance API

UltimateBankingApiProvider.get() exposes:

Money operations

ApiResult getBalance(UUID accountId);
ApiTransactionResult deposit(UUID accountId, BigDecimal amount, String reference);
ApiTransactionResult withdraw(UUID accountId, BigDecimal amount, String reference);
ApiTransactionResult transfer(UUID from, UUID to, BigDecimal amount, String reference);
ApiTransactionResult depositToPrimary(UUID playerId, BigDecimal amount, String reference);
ApiTransactionResult withdrawFromPrimary(UUID playerId, BigDecimal amount, String reference);
ApiTransactionResult transferFromPrimary(UUID playerId, UUID to, BigDecimal amount, String reference);
ApiTransactionResult transferToPrimary(UUID from, UUID playerId, BigDecimal amount, String reference);

Whole-dollar long overloads and legacy ApiResult deposit/withdraw/transfer overloads remain available.

Validation

  • accountExists, bankExists, shopExists
  • accountCanSend, accountCanReceive
  • primaryAccountCanSend, primaryAccountCanReceive
  • validateAccountCanSend, validateAccountCanReceive, validateAccountCanInteract
  • accountBelongsToBank, accountIsFrozen, accountIsPrimary
  • bankAcceptsTransactions

Call validation immediately before an operation only as UX assistance; the operation still performs authoritative validation.

Account and bank snapshots

  • getAccountSnapshot, getPrimaryAccountSnapshot
  • getPlayerAccounts, getPlayerAccountIds, getBankAccounts
  • getBankSnapshot, getBanks
  • getTransactionSnapshot, getAccountTransactions, getPlayerTransactions
  • setPrimaryAccount

Account transaction lists are bounded by the requested limit and by the server's retained history (AccountTransactionLogLimit, default 20).

Ownership and aggregate helpers

  • playerOwnsAccount, playerOwnsBank, playerOwnsAnyBank
  • getPlayerOwnedBanks
  • playerOwnsShop, playerOwnsAnyShop, getPlayerOwnedShopIds
  • playerHasAnyAccount, playerHasPrimaryAccount
  • playerHasAvailableAccount, playerHasAvailablePrimaryAccount, playerHasFrozenAccount
  • getPlayerTotalBalance, getPlayerPrimaryBalance, getPlayerAccountCount
  • getBankTotalDeposits, getBankReserve, getBankStatus

Merchant and instruments

  • shopPurchase with payer, merchant, shop name, and reference
  • issueBankNote
  • issueCheque
  • giveDollarBills, takeDollarBills
  • giveCoins, takeCoins
  • supported denomination, stack-creation, count, and cash-on-hand helpers

Bill denominations are dollars: 1, 2, 5, 10, 20, 50, 100. Coin denominations are cents: 1, 5, 10, 25, 50.

Notification API

New integrations should use sendNotification(playerId, request).

var request = ApiNotificationRequest.transaction("Payment settled")
        .id("auction:settlement:" + orderId)
        .channel("auction_house")
        .source("Ultimate Auction System")
        .title("Settlement complete")
        .detail("The seller account was credited.")
        .priority(ApiNotificationPriority.NORMAL)
        .durationMs(5500)
        .build();

ApiNotificationResult result = finance.sendNotification(playerId, request);

Types: SUCCESS, ERROR, WARNING, INFO, TRANSACTION, SECURITY, MESSAGE, PROGRESS, SYSTEM.

Priorities: LOW, NORMAL, HIGH, CRITICAL.

Placements: AUTO, TOP_RIGHT, TOP_CENTER, BOTTOM_RIGHT.

Use a stable request ID and replaceExisting=true to update progress/state in place. Use dismissNotification, clearNotificationChannel, or clearNotifications for cleanup. Offline targets are not silently queued.

The original sendUiAlert overloads and ApiAlertTone remain binary-compatible for older addons.

Market Price API

ApiShopPriceStatistics stats = finance.getItemShopPriceStatistics(
        stack,
        ApiShopPriceScope.REGULAR
);

Scopes:

  • REGULAR: registered, setup-complete, currently open shops; creative displays excluded
  • INCLUDE_ALL: every indexed shop display, including creative/unregistered displays
  • ALL_SHELVES_EXCLUDE_CREATIVE: every indexed non-creative display
  • CREATIVE_ONLY: creative displays only

The result exposes availability, item ID, sample count, and median/average/minimum/maximum price in cents. Convenience methods exist for every scope.

General Server API

UltimateBankingApiProvider.server() provides:

  • isAvailable
  • getSnapshot
  • getAvailableFeatures, isFeatureAvailable
  • getOnlinePlayerIds
  • getPlayerPortfolio

ApiServerSnapshot contains API version, online-player count, bank/account/shop counts, active-heist count, and feature flags.

Feature flags: BANKING, SHOPS, HEISTS, SMARTPHONE, SAFETY_DEPOSIT_BOXES, RFID_ACCESS, PHYSICAL_CURRENCY, WALLET, OWNER_PC.

ApiPlayerPortfolioSnapshot contains account count, primary account, total balance, owned/accessed bank IDs, owned/accessed shop IDs, and current heist session ID.

Bank Management API

UltimateBankingApiProvider.banks() provides:

Reads

  • getBanks, getBank, findBank
  • getOwnedBanks, getAccessibleBanks
  • playerOwnsBank, playerOwnsAnyBank
  • playerCanAccessBank
  • playerCanManageSafeArea, playerCanAccessProtectedSafeArea
  • isBankUnderAttack
  • getStaffing
  • getSafeDepositSetup

ApiBankManagementSnapshot includes identity/owner/status, central-bank flag, account count, deposits, reserve requirements/ratio, outstanding loans, lendable amount, rate, premise/safe/vault/readiness counts, staff/teller counts, and attack state.

ApiBankStaffingSnapshot contains immutable employee and teller records. Employees include role, salary, online state, and Safe Access. Tellers include entity identity, variant, position, active state, and bank-bound state.

ApiSafeDepositSetupSnapshot contains enabled/readiness counts, human-readable blockers, and premises. Each ApiBankPremiseSnapshot provides bounds, exit/facing, access mode, safe/vault counts, and ready-vault count.

Mutations

ApiManagementResult setEmployeeSafeAccess(
        UUID actorId, UUID bankId, UUID employeeId, boolean allowed);

ApiManagementResult setInterestRate(
        UUID actorId, UUID bankId, double annualPercent);

The actor must have the same permission the in-game management action requires.

Shop Management API

UltimateBankingApiProvider.shops() provides:

Discovery and ownership

  • getShops, getShop, findShop
  • getOwnedShops, getAccessibleShops
  • shopExists, playerOwnsShop, playerOwnsAnyShop
  • getPlayerRole, playerCanManageShop, playerCanBuildInShop

State and limits

  • isShopSetupComplete
  • isShopCurrentlyOpen
  • getMaximumShopsPerOwner
  • getSupportedShopTypes
  • getSupportedParticipantRoles

ApiShopManagementSnapshot includes owner/name/type/display type, level/revenue/next target, used/capacity claim volume, plot and stockroom counts, setup/open state, display/cashier/order-pallet limits, and participants. Each participant includes role plus computed management/build permissions.

Mutations

createShop(ownerId, name, type);
renameShop(ownerId, shopId, newName);
setShopType(ownerId, shopId, type);
setOpeningHours(ownerId, shopId, schedule);
setParticipantRole(ownerId, shopId, playerId, role);
removeParticipant(ownerId, shopId, playerId);
deleteShop(ownerId, shopId, confirmationName);

The schedule accepts the same payload as the Owner PC, for example ALL|09:00|21:00 or MON|9:00 AM|5:30 PM. Roles are the values returned by getSupportedParticipantRoles.

Heist API

UltimateBankingApiProvider.heists() provides:

State

  • getSessions, getActiveSessions, getSession, getPlayerSession
  • getTargets, getTarget
  • isPlayerInHeist, isPlayerInActiveHeist, isBankUnderAttack
  • player/bank cooldown and victim-protection remaining milliseconds
  • effective maximum crew size, countdown ticks, and duration ticks

ApiHeistSessionSnapshot includes phase/timestamps/deadline, target bounds/exit, loot/alarm state, members, active drills/hacks, completed hacks, breached targets, and cancel votes.

ApiHeistTargetSnapshot includes premise bounds/exit, owner-PC/vault-door positions, eligibility/blockers, physical-loot source count, and bank cooldown.

Planning actions

createPlanningSession(playerId);
invite(leaderId, playerName);
respondToInvite(playerId, accepted);
leave(playerId);
selectTarget(leaderId, bankId, premiseId);
setReady(playerId, ready);
startCountdown(leaderId);
cancelCountdown(leaderId);
abandon(playerId);

Actors must be online and calls must run on the server thread.

Heist extension points

  • Listen for HeistLifecycleEvent stages: STARTED, ALARMED, SUCCEEDED, FAILED.
  • Register HeistDoorAdapter with HeistDoorAdapterRegistry to breach/restore modded doors.
  • Register HeistLootValueProvider with HeistLootValueRegistry to value custom items.
  • Unregister adapters/providers when your integration unloads where applicable.

Registry implementations isolate provider exceptions so one addon does not break the heist loop.

Geometry Records

ApiBlockPosition stores dimension and integer coordinates.

ApiBlockBounds normalizes min/max coordinates and exposes volume() and contains(position). Use these API records instead of depending on internal claim classes.

Placeholders

resolvePlaceholder, resolvePlaceholders, and getSupportedPlaceholders support player balances/accounts and bank identity/status/reserve/deposit values. Raw variants return decimal strings for sorting; formatted variants use UBS money formatting.

Compatibility

  • Check getApiVersion() before using a surface introduced after your minimum version.
  • Declare UBS as a required or optional NeoForge dependency; never shade UBS into your jar.
  • Keep optional integration classes isolated until ModList.get().isLoaded("ultimatebankingsystem") is true.
  • Do not retain internal UBS objects or mutate NBT directly. Use IDs, snapshots, and API methods.

Clone this wiki locally