当前位置：首页 > news >正文

libsm64 API详解：马里奥状态控制与物理交互完整教程

news 2026/7/21 16:12:17

libsm64 API详解：马里奥状态控制与物理交互完整教程

【免费下载链接】libsm64Mario 64 as a library for use in external game engines项目地址: https://gitcode.com/gh_mirrors/li/libsm64

libsm64是一个将经典游戏《超级马里奥64》的核心功能封装为库的开源项目，让开发者能够在自己的游戏引擎中轻松集成马里奥的完整物理系统和动画。这个强大的库提供了完整的马里奥状态控制与物理交互API，让您可以精确控制马里奥的动作、状态和物理行为。😊

🚀 libsm64核心功能概览

libsm64通过提供简洁的C语言API，将马里奥的完整游戏逻辑暴露给外部程序。主要功能包括：

马里奥状态管理：创建、更新和删除马里奥实例
物理系统集成：完整的碰撞检测和物理模拟
动画控制：精确控制马里奥的动画状态和帧
声音系统：集成原版游戏音效和音乐
渲染支持：提供几何缓冲区用于3D渲染

📦 安装与初始化

首先需要从仓库克隆项目并构建库文件：

git clone https://gitcode.com/gh_mirrors/li/libsm64 cd libsm64 make

初始化libsm64需要提供原版SM64 ROM文件：

#include "libsm64.h" uint8_t *rom = utils_read_file_alloc("baserom.us.z64", &romSize); uint8_t *texture = malloc(4 * SM64_TEXTURE_WIDTH * SM64_TEXTURE_HEIGHT); sm64_global_init(rom, texture); sm64_audio_init(rom);

🎮 马里奥实例管理

创建马里奥实例

使用sm64_mario_create()函数创建马里奥实例，返回一个唯一的ID：

int32_t marioId = sm64_mario_create(0, 1000, 0); // 在坐标(0,1000,0)创建马里奥

更新马里奥状态

sm64_mario_tick()是核心更新函数，每帧调用以处理输入并更新状态：

struct SM64MarioInputs inputs = { .camLookX = cameraLookX, .camLookZ = cameraLookZ, .stickX = stickX, .stickY = stickY, .buttonA = buttonAState, .buttonB = buttonBState, .buttonZ = buttonZState }; struct SM64MarioState state; struct SM64MarioGeometryBuffers geometry; sm64_mario_tick(marioId, &inputs, &state, &geometry);

删除马里奥实例

当不再需要马里奥实例时，使用sm64_mario_delete()进行清理：

sm64_mario_delete(marioId);

🎯 马里奥状态控制API详解

位置与方向控制

libsm64提供多种函数来控制马里奥的位置和方向：

// 设置马里奥位置 sm64_set_mario_position(marioId, x, y, z); // 设置马里奥旋转角度（欧拉角） sm64_set_mario_angle(marioId, pitch, yaw, roll); // 设置马里奥面向角度（仅Y轴） sm64_set_mario_faceangle(marioId, yaw);

速度与运动控制

精确控制马里奥的运动状态：

// 设置三维速度向量 sm64_set_mario_velocity(marioId, vx, vy, vz); // 设置前进速度（沿面向方向） sm64_set_mario_forward_velocity(marioId, speed);

动作与动画控制

libsm64允许直接控制马里奥的动作状态：

// 设置马里奥动作（跳跃、游泳、滑行等） sm64_set_mario_action(marioId, ACTION_JUMP); // 设置带参数的动作 sm64_set_mario_action_arg(marioId, ACTION_DIVE, diveParameter); // 设置特定动画 sm64_set_mario_animation(marioId, MARIO_ANIM_BACKFLIP); // 设置动画帧 sm64_set_mario_anim_frame(marioId, frameNumber);

状态标志控制

马里奥的状态标志控制各种游戏机制：

// 设置状态标志（无敌、飞行等） sm64_set_mario_state(marioId, MARIO_UNKNOWN_08 | MARIO_METAL_CAP);

生命值与能力管理

// 设置生命值（0x100为满血） sm64_set_mario_health(marioId, 0x100); // 设置无敌时间 sm64_set_mario_invincibility(marioId, 30); // 30帧无敌 // 造成伤害 sm64_mario_take_damage(marioId, damageAmount, damageType, x, y, z); // 治疗马里奥 sm64_mario_heal(marioId, healAmount); // 杀死马里奥 sm64_mario_kill(marioId);

帽子能力交互

// 与帽子互动（获取能力） sm64_mario_interact_cap(marioId, MARIO_VANISH_CAP, 600, 1); // 延长帽子能力时间 sm64_mario_extend_cap(marioId, 300); // 延长300帧

攻击与交互

// 执行攻击并检测命中 bool hit = sm64_mario_attack(marioId, targetX, targetY, targetZ, hitboxHeight);

🌊 环境交互控制

水位与毒气设置

// 设置水位高度 sm64_set_mario_water_level(marioId, waterLevel); // 设置毒气高度 sm64_set_mario_gas_level(marioId, gasLevel);

🏗️ 表面与碰撞系统

静态表面加载

libsm64支持加载自定义碰撞表面：

struct SM64Surface surfaces[] = { {.type = SURFACE_DEFAULT, .vertices = {{0,0,0}, {100,0,0}, {0,0,100}}}, // 更多表面... }; sm64_static_surfaces_load(surfaces, surfaceCount);

动态表面对象

创建可移动的表面对象：

struct SM64SurfaceObject surfaceObj = { .transform = {.position = {x, y, z}, .eulerRotation = {rx, ry, rz}}, .surfaceCount = numSurfaces, .surfaces = surfaces }; uint32_t surfaceObjId = sm64_surface_object_create(&surfaceObj); // 移动表面对象 struct SM64ObjectTransform newTransform = {.position = {newX, newY, newZ}}; sm64_surface_object_move(surfaceObjId, &newTransform);

碰撞检测API

libsm64提供完整的碰撞检测功能：

// 查找墙壁碰撞 struct SM64WallCollisionData wallData; int32_t numWalls = sm64_surface_find_wall_collisions(&wallData); // 查找天花板 struct SM64SurfaceCollisionData *ceil; float ceilHeight = sm64_surface_find_ceil(x, y, z, &ceil); // 查找地面 struct SM64FloorCollisionData *floor; float floorHeight = sm64_surface_find_floor_height_and_data(x, y, z, &floor); // 查找水面高度 float waterLevel = sm64_surface_find_water_level(x, z); // 查找毒气高度 float gasLevel = sm64_surface_find_poison_gas_level(x, z);

🎵 音频系统集成

声音播放控制

// 播放特定音效 sm64_play_sound(SOUND_GENERAL_BOING1, position); // 全局播放音效（无位置） sm64_play_sound_global(SOUND_MENU_STAR_SOUND); // 设置音量 sm64_set_sound_volume(1.0f); // 最大音量

背景音乐控制

// 播放背景音乐 sm64_play_music(0, SEQ_LEVEL_GROUND | SEQ_VARIATION, 0); // 停止背景音乐 sm64_stop_background_music(SEQ_LEVEL_GROUND); // 淡出音乐 sm64_fadeout_background_music(SEQ_LEVEL_GROUND, 60); // 60帧淡出 // 获取当前播放的音乐 uint16_t currentMusic = sm64_get_current_background_music();

📊 数据结构详解

SM64MarioState结构

这个结构包含马里奥的完整状态信息：

struct SM64MarioState { float position[3]; // 三维位置 float velocity[3]; // 三维速度 float faceAngle; // 面向角度 float forwardVelocity; // 前进速度 int16_t health; // 生命值 uint32_t action; // 当前动作 int32_t animID; // 动画ID int16_t animFrame; // 动画帧 uint32_t flags; // 状态标志 uint32_t particleFlags; // 粒子效果标志 int16_t invincTimer; // 无敌计时器 };

SM64MarioInputs结构

输入控制结构：

struct SM64MarioInputs { float camLookX, camLookZ; // 摄像机方向 float stickX, stickY; // 摇杆输入 uint8_t buttonA, buttonB, buttonZ; // 按钮状态 };

SM64Surface结构

碰撞表面定义：

struct SM64Surface { int16_t type; // 表面类型 int16_t force; // 作用力 uint16_t terrain; // 地形类型 int32_t vertices[3][3]; // 三个顶点的坐标 };

🔧 高级使用技巧

多马里奥实例管理

libsm64支持创建多个马里奥实例，每个实例独立运行：

// 创建多个马里奥 int32_t mario1 = sm64_mario_create(0, 1000, 0); int32_t mario2 = sm64_mario_create(100, 1000, 100); // 分别更新每个马里奥 sm64_mario_tick(mario1, &inputs1, &state1, &geo1); sm64_mario_tick(mario2, &inputs2, &state2, &geo2);

自定义调试输出

注册自定义调试输出函数：

void my_debug_print(const char *message) { printf("[libsm64] %s\n", message); } sm64_register_debug_print_function(my_debug_print);

自定义声音播放

注册自定义声音播放函数：

void my_play_sound(uint32_t soundBits, float *pos) { // 根据soundBits播放对应音效 // pos为3D位置，可用于空间音频 } sm64_register_play_sound_function(my_play_sound);

🎨 渲染集成

几何数据获取

每帧更新后，可以获取马里奥的几何数据用于渲染：

struct SM64MarioGeometryBuffers geometry; geometry.position = malloc(sizeof(float) * 9 * SM64_GEO_MAX_TRIANGLES); geometry.normal = malloc(sizeof(float) * 9 * SM64_GEO_MAX_TRIANGLES); geometry.color = malloc(sizeof(float) * 9 * SM64_GEO_MAX_TRIANGLES); geometry.uv = malloc(sizeof(float) * 6 * SM64_GEO_MAX_TRIANGLES); sm64_mario_tick(marioId, &inputs, &state, &geometry); // geometry.numTrianglesUsed 包含实际使用的三角形数量 // geometry.position/normal/color/uv 包含顶点数据

纹理数据

初始化时提取的纹理数据可以用于渲染：

// 纹理尺寸定义在libsm64.h中 #define SM64_TEXTURE_WIDTH (64 * 11) // 704像素 #define SM64_TEXTURE_HEIGHT 64 // 64像素 // 纹理格式为RGBA，每个像素4字节 uint8_t *texture = malloc(4 * SM64_TEXTURE_WIDTH * SM64_TEXTURE_HEIGHT); sm64_global_init(rom, texture);