mlib - 轻量级数学与游戏工具库

公告！

请更换至mini-game-tools

该库将不再维护

但是本仓库不会删除

一个零外部依赖的Python工具库，提供分数运算、数学函数、随机数生成、颜色处理、几何碰撞检测、向量运算和存档系统。

特性

• 🧮 sfrac - 零依赖的分数类，支持精确运算
• 📐 smath - 基础数学函数（三角函数、对数、取整等），支持复数运算
• 🎲 srandom - 可种子控制的随机数生成器
• 🎨 scolor - RGB/HSV颜色转换、插值、常用颜色
• 📏 sgeometry - 2D/3D几何类型与碰撞检测（矩形、圆形、线段、AABB、球体）
• ➡️ svector - 二维/三维向量运算
• 💾 ssaver - SGT格式存档系统，带校验和验证
• 📦 spathfinder - BFS寻路

如何使用

分数运算 (sfrac)

from mlib import frac

a = frac(1, 2)  # 1/2
b = frac(3, 4)  # 3/4

print(a + b)          # 1.25
print(repr(a * b))    # 3/8
print(float(a / b))   # 0.6666666666666666
# 注意，这个分数在处理极大或极小数时容易产生误差

数学函数 (smath)

from mlib import *

# 三角函数（支持复数）
print(sin(pi/2))      # 1.0
print(cos(1+2j))      # 复数结果

# 对数
print(log(100))       # 2.0
print(ln(e**2))       # 2.0

# 取整与映射
print(floor(3.7))     # 3
print(ceil(3.2))      # 4
print(map(50, 0,100, 0,360))  # 180.0

随机数 (srandom)

from mlib import SimpleRNG

rng = SimpleRNG("my_seed")
print(rng.randint(1, 10))     # 随机整数
print(rng.random())            # [0,1) 浮点数
print(rng.choice(["a","b","c"]))  # 随机选择
print(rng.sample_by_y(lambda x: x**2, 3, 10) #根据函数高度取随机数
# 🎲 1.1.1新增：随机抽样与洗牌
# 随机抽牌（不重复）
cards = list(range(20))
hand = rng.sample(cards, 5)    # 抽5张，例如 [7, 1, 3, 6, 19]

# 打乱顺序（原地修改）
rng.shuffle(cards)              # cards 顺序被打乱
print(cards)                    # 例如 [7, 1, 12, 15, 18, 16, ...]

颜色处理 (scolor)

from mlib import *

# RGB操作
print(hex_to_rgb("#FF0000"))   # (255, 0, 0)
print(rgb_to_hex(0,255,0))     # #00ff00

# HSV转换
hsv = rgb_to_hsv(255,0,0)      # (0.0, 1.0, 1.0)
rgb = hsv_to_rgb(120, 1, 1)    # (0, 255, 0)

# 颜色插值
c1 = RED
c2 = BLUE
print(lerp(c1, c2, 0.5))       # (127, 0, 127)

# 颜色混合 - 正片叠底
blend(GREEN, PURPLE, "multiply") # (0, 112, 0)

#颜色混合 - 滤色

blend(GREEN, PURPLE, "screen") # (147.0, 255.0, 219.0)

几何碰撞 (sgeometry)

from mlib import *

# 2D矩形
rect = Rect(0,0,100,100)
print(rect.collide_point(50,50))      # True
print(rect.collide_circle(Circle((150,150),20)))  # False

# 线段
line = Line2((0,0),(100,100))
print(line.closest_point((50,0)))     # (25,25)

# 3D AABB
box = AABB((0,0,0),(10,10,10))
print(box.collide_point((5,5,5)))     # True

向量运算 (svector)

from mlib import vec2, vec3

v2 = vec2(3,4)
print(v2.length())          # 5.0
print(v2.normalize())       # (0.6, 0.8)

v3 = vec3(1,0,0)
w3 = vec3(0,1,0)
print(v3.cross(w3))         # (0,0,1)

存档系统 (ssaver)

from mlib import SGTsaver
from mlib import vec2

# 保存数据
saver = SGTsaver()
saver.set_value(
    score=100,
    name="hero",
    position=vec2(10,20),
    items=["sword","potion"]
)
saver.save("game.sgt")

# 加载数据
loaded = SGTsaver().load("game.sgt")
print(loaded["name"])       # "hero"
print(loaded["position"])   # (10.0, 20.0)

基本寻路

from mlib import bfs

# 地图：0可走，1障碍
grid = [
    [0,0,0,0,0],
    [0,1,1,1,0],
    [0,0,0,0,0],
    [0,1,1,1,0],
    [0,0,0,0,0]
]

# 找路径
path = bfs(grid, (0,0), (4,4))

# 输出路径
for p in path:
    print(f"({p.x}, {p.y})")

配合 vec2

from mlib import vec2, bfs

start = vec2(0, 0)
end = vec2(4, 4)

path = bfs(grid, start, end)
print(f"需要 {len(path)} 步")
print(f"第一步: {path[1]}")

无路可走

path = bfs(grid, (0,0), (4,4))
if path is None:
    print("到不了终点")

SGT文件格式

SGTv1                  # 魔数（被跳过）
#score=100            # 整数
#name="hero"          # 字符串
#position=(10,20)     # 向量
#items=["sword","potion"]  # 列表
#hash=123456          # 校验和

• # 开头的行为有效数据
• 非 # 开头的行会被跳过
• 自动计算并验证校验和

依赖

• 无外部依赖，纯Python实现
• 兼容Python 3.6+

许可证

MIT License

关于版本号(从1.5.0开始有效)

1.5.0 0:当出现修复bug时，该号加一 5:当出现向下兼容的功能时，该号加一 1:当出现不向下兼容的API时，该号加一