XmobiTea Helper

Static Unity helper package for Unix-millisecond time, local reset timestamps, stateless energy math, clamped remap, casual random values, and one editor screenshot menu item.

AI Entry Points

Open the smallest file for the task:

| Need | Use | | --- | --- | | Generate common helper code | AI_USAGE.md | | Setup, imports, editor/runtime boundary, menu path | AI_SETUP.md | | Unix ms, TTL, cooldown, local day/week/month reset | AI_CustomDateTime.md | | Stamina, refill, bonus energy, spend/add logic | AI_CustomEnergy.md | | Clamped float remap | AI_CustomMath.md | | Casual random int/float | AI_CustomRandom.md | | Editor screenshot menu item | AI_TakeScreenShotEditor.md | | Exact API index | AI_API_REFERENCE.md | | Behavior index | AI_BEHAVIOR.md | | Agent guardrails | AGENTS.md | | Missing or conflicting docs | source files |

Runtime Contract

• Runtime namespace: XmobiTea.MiniHelper
• Runtime helpers are static and require no scene setup.
• Time values are Unix milliseconds.
• CustomDateTime.GetDateTime(long) returns UTC DateTime.
• Local reset helpers use local calendar boundaries.
• CustomEnergy derives normal energy from tsDoneRefillEnergy.
• CustomEnergy keeps bonus energy as separate caller-owned state.
• CustomRandom uses one static System.Random.
• TakeScreenShotEditor is editor-only.

Setup

1. Add using XmobiTea.MiniHelper; for runtime helpers.
2. Call static helpers directly. No component, asset, prefab, or initialization call is required.
3. Capture one nowMs for each time or energy operation.
4. Validate energy and math inputs before mutation.
5. Use XmobiTea.MiniHelper.Editor only from editor assemblies when calling the screenshot API directly.

See AI_SETUP.md for exact setup rules and error cases.

Usage

Current time or TTL:

using XmobiTea.MiniHelper;

var nowMs = CustomDateTime.CurrentMillitime();
var expiresAtMs = nowMs + CustomDateTime.ONE_MINUTE_MILLITIME * 5L;

Next local daily reset:

using XmobiTea.MiniHelper;

var nowMs = CustomDateTime.CurrentMillitime();
var nextResetMs = CustomDateTime.Tomorrow0hMillitime(nowMs);

Safe energy spend:

using XmobiTea.MiniHelper;

var nowMs = CustomDateTime.CurrentMillitime();

if (amount >= 0 &&
    refillOneMs > 0 &&
    maxEnergy > 0 &&
    bonusEnergy >= 0 &&
    CustomEnergy.CanUse(amount, bonusEnergy, tsDoneRefillEnergy, refillOneMs, nowMs, maxEnergy))
{
    CustomEnergy.Use(amount, ref bonusEnergy, ref tsDoneRefillEnergy, refillOneMs, nowMs);
}

Clamped remap and random index:

using XmobiTea.MiniHelper;

var normalized = minInput < maxInput
    ? CustomMath.Lerp(input, minInput, maxInput, 0f, 1f)
    : 0f;

var index = itemCount > 0
    ? CustomRandom.Range(0, itemCount)
    : -1;

Editor screenshot:

Unity menu: XmobiTea Tools/Helper/TakeScreenShot
Shortcut: Ctrl/Cmd+G
Output: project-root ScreenShot/{width}x{height}_{DateTime.Now.Ticks}.png

Important Behavior Notes

• CustomEnergy treats full normal energy as tsDoneRefillEnergy < nowMs, not <=.
• At exact equality, CustomEnergy.GetRefillNextIn(...) and CustomEnergy.GetRefillFullIn(...) can return zero while IsFull(...) is still false and GetNormal(...) can still be maxEnergy - 1.
• CustomEnergy does not validate refill interval, energy signs, affordability, or corrupt stored state.
• CustomMath.Lerp(...) clamps x with x0 as the lower bound and x1 as the upper bound; use x0 < x1.
• CustomRandom.Range(int, int) uses exclusive max.

Do And Do Not

• Do use CustomDateTime for Unix-millisecond timestamps and simple local reset boundaries.
• Do convert CustomDateTime.GetDateTime(ms).ToLocalTime() for player-facing local display.
• Do validate energy input and persist bonusEnergy plus tsDoneRefillEnergy together.
• Do keep screenshot code in editor-only assemblies.
• Do not treat local reset helpers as UTC-day helpers.
• Do not treat tsDoneRefillEnergy as a last-refill timestamp.
• Do not call CustomEnergy.Use(...) without CanUse(...) when failure must be rejected.
• Do not assume CustomRandom matches UnityEngine.Random seeding or determinism.

Common Mistakes

• Passing .NET ticks instead of Unix milliseconds.
• Treating GetDateTime(...) as local time without calling ToLocalTime().
• Using tsDoneRefillEnergy == nowMs as a clean full-energy state.
• Calling CustomMath.Lerp(...) with identical bounds.
• Calling CustomMath.Lerp(...) with reversed source bounds.
• Using CustomRandom.Range(0, itemCount) as a collection index without checking itemCount > 0.
• Using the screenshot helper from runtime gameplay code.

Package Metadata

• Package: com.xmobitea.changx.mini-helper
• Runtime assembly: com.xmobitea.changx.mini-helper.runtime
• Editor assembly: com.xmobitea.changx.mini-helper.editor
• Declared package dependency: com.xmobitea.changx.app 1.5.2
• Minimum Unity version declared: 2022.3
• License: Apache-2.0