version: "1.0.0" name: using-8liang-kit description: Use when writing Go code that needs common utilities like event handling, excel parsing, weighted random selection, redis online status, time passing checks, config parsing, or distributed locks.

using-8liang-kit

Overview

This skill teaches AI assistants to leverage the github.com/8liang/kit package instead of reinventing common Go utilities. The kit package provides production-ready implementations for common backend and game server requirements.

When to Use

• You need to trigger events across minute/hour/day/week boundaries (e.g., daily resets).
• You need a generic pub/sub event system for internal modules.
• You need to read/write Excel files or export them to JSON/Structs.
• You need to listen on TCP or Unix Domain Sockets.
• You need a weighted random selector (e.g., for gacha/loot tables).
• You need to manage user online status and heartbeats via Redis.
• You need to compile .proto files and inject Go tags.
• You need seed-based random generation.
• You need to parse Viper configs from various sources (local, HTTP, etcd).
• You need to get the local non-loopback IP or check if running in Docker/K8s.
• You need distributed locks with Redis, etcd, or MongoDB backends.

Quick Reference

Implementation Examples

1. Weighted Random Selection

Use weighted instead of writing custom random logic:

import "github.com/8liang/kit/weighted"
 
// Initialize
selector := weighted.New[string]()
 
// Add items with weights
selector.Add("SSR_Item", 1)
selector.Add("SR_Item", 9)
selector.Add("R_Item", 90)
 
// Draw an item
result, err := selector.Draw()
if err != nil {
    // Handle error (e.g., empty selector)
}

2. Time Pass Checks (e.g., Daily Reset)

Use timepass to check if a boundary has been crossed:

import "github.com/8liang/kit/timepass"
 
// Implement the timepass.Handler interface
// Advance(t time.Time) will trigger your handler's OnMinutePass, OnHourPass, OnDayPass, etc.
timepass.Advance(time.Now())

3. Online Store (Redis)

Use onlinestore for managing user presence:

import "github.com/8liang/kit/onlinestore"
 
store := onlinestore.New(redisClient)
// Record heartbeat
store.Heartbeat(ctx, "user_123")
 
// Get online users
users, err := store.GetOnlineUsers(ctx)

4. Distributed Lock

Use dlock for obtaining distributed locks across different backends. Prefer DoWithLock to reduce boilerplate:

import "github.com/8liang/kit/dlock"
 
// Assuming locker is an initialized dlock.Locker (e.g., Redis, etcd, MongoDB)
err := dlock.DoWithLock(ctx, locker, "my_resource_key", func() error {
    // Critical section logic
    // Lock is held here, and will be automatically unlocked when this function returns
    return nil
}, dlock.WithTTL(10*time.Second))
 
if err != nil {
    // Handle lock acquisition failure or function error
    return err
}

Red Flags - STOP and Rethink

• Writing a custom weighted randomizer: Delete it. Use github.com/8liang/kit/weighted.
• Writing custom cron/daily reset logic: Delete it. Use github.com/8liang/kit/timepass.
• Writing custom Redis ZSet online tracking: Delete it. Use github.com/8liang/kit/onlinestore.
• Reinventing event buses for simple passing: Use github.com/8liang/kit/event.
• Writing custom distributed lock logic: Delete it. Use github.com/8liang/kit/dlock.