Cocos Creator 教程项目：Duang Sheep

安装与兼容性

安装方式有两种：

• 直接执行 gem install leaderboard；
• 在 Gemfile 中加入 gem 'leaderboard' 后通过 Bundler 安装。

使用前需要确保 Redis 服务已经运行。README 明确说明 Redis 的配置不在本文档范围内，需要参考 Redis 官方文档。

兼容性方面，仓库称该 gem 已在 Ruby 2.2.1 下构建和测试；同时提示它应当也能在更早的 Ruby 版本（如 1.8.7 或 1.9.3）上工作，因为当前并未使用 Ruby 2.x 特有的能力。

创建排行榜与选项配置

引入库后，可以用 Leaderboard.new('highscores') 创建或连接一个名为 highscores 的排行榜。若同名排行榜已存在，则相当于附着到它上面。

Leaderboard::DEFAULT_OPTIONS 定义了默认选项，包括：

• :page_size：分页大小，默认 25；
• :reverse：是否反向排序，默认 false，设为 true 时按分数从低到高排列；
• :member_key、:rank_key、:score_key：控制 leaders、around_me 等调用返回哈希中的字段名；
• :member_data_key、:member_data_namespace：可选成员数据的键名与命名空间；
• :global_member_data：可选成员数据是按排行榜隔离（false）还是全局共享（true）。

Redis 连接参数可以在初始化时通过第三个参数传入，例如指定 :host、:port、:db；也可以通过 :redis_connection 传入一个已存在的 Redis 连接对象。若要让多个排行榜复用同一连接，需要在实例化下一个排行榜前重置选项哈希。分页大小也可以在实例创建后通过 page_size= 修改。

成员排名与可选成员数据

使用 rank_member 可以把成员加入排行榜并赋予分数。对同一成员重复调用会更新其分数。total_members 和 total_pages 可用于查看排行榜规模。

rank_member 还接受可选的 member_data 参数，用于存放成员的附加信息，例如把成员 ID 作为排行榜成员、同时保存用于展示的用户名。README 建议用 JSON 编码一个 Hash 来存储。配套方法包括：

• member_data_for：读取成员数据；
• update_member_data：更新成员数据；
• remove_member_data：删除成员数据。

需要注意，删除排行榜时所有成员数据也会一并删除。另外，如果使用了可选成员数据，调用 remove_members_in_score_range 或 remove_members_outside_rank 会在成员数据哈希中留下残留数据，原因是底层 Redis 的 zremrangebyscore 只返回被删除的数量，不返回被删除的成员。

查询单个成员时，可以用 score_for 获取分数、用 rank_for 获取名次。

读取排行榜数据

leaders(page) 用于获取指定页的排行榜数据，返回包含成员、名次、分数的哈希数组。leaders、all_leaders、around_me、members_from_score_range、members_from_rank_range、ranked_in_list 等调用支持一组通用选项：

• :with_member_data：是否返回可选成员数据；
• :page_size：临时改变该次调用的分页大小；
• :members_only：只返回成员名，不带分数和名次；
• :sort_by：可选 :none（默认）、:score、:rank；
• :include_missing：是否返回未上榜的成员。

members 和 members_in 是 leaders 和 leaders_in 的别名。all_leaders / all_leaders_from（别名 all_members / all_members_from）会返回整个排行榜的数据，README 提醒应谨慎使用。

其他常用读取方法包括：

• around_me：获取某个成员上下相邻的排名页；
• ranked_in_list：对任意成员列表（如好友列表）批量查询名次与分数，并可配合 :sort_by 排序；
• members_from_score_range：按分数区间取成员；
• member_at：取指定名次上的单个成员；
• members_from_rank_range：按名次区间取成员。

条件排名与其他能力

README 还介绍了 rank_member_if：通过传入 lambda 有条件地给成员排名。该 lambda 会收到成员名、当前分数（成员未上榜时可能为 nil）、新分数、成员数据等参数，具体参数列表在 README 中被截断，使用前建议查阅完整文档。

大纲中还列出了「一次给多个成员排名」「跨多个排行榜给成员排名」「其他排行榜类型」「其他实用方法」「性能指标」「批量插入性能」「Ports」等章节，说明该库还覆盖批量操作与性能相关话题；这些内容在提供的 README 摘录中未展开，建议以仓库原文为准。

学习与使用建议

这个库适合作为理解「Redis 有序集合 + 排行榜」模式的入门材料：它把分页、区间查询、周边排名、成员附加数据等常见需求封装成方法，代码结构清晰。使用前先确认 Redis 可用，再根据业务决定分页大小、排序方向以及成员数据是全局还是按榜隔离。对于需要批量写入或关注性能的场景，应重点阅读 README 中的性能与批量插入章节。