SoundsPack Core

项目介绍

SoundsPack Core 是一个 Minecraft 音频包核心库，该库提供了创建Minecraft 音频包配置的功能，使开发者能够轻松地创建自定义音频包。

安装

使用 npm 安装：

npm install soundspack-core

或使用 pnpm 安装：

pnpm add soundspack-core

或使用 deno 安装：

deno add jsr:@alwolf/soundspack-core

基本用法

import SoundPack from 'soundspack-core';

// 创建一个新的声音包
const soundPack = new SoundPack('我的声音包', 1, '这是一个自定义声音包', '作者名称');

// 设置声音
const sounds = soundPack.setSound([
  { name: 'example_sound.ogg', volume: 1, pitch: 1 }
]);

// 创建声音配置
const soundsConfig = soundPack.createSoundsConfig([
  {
    keyValue: 'example',
    category: 'player',
    subtitle: '示例声音',
    sounds: sounds
  }
]);

// 获取声音包元数据
const mcmeta = soundPack.getMcmeta();

API 文档

SoundPack 类

SoundPack 是核心类，用于创建和管理 Minecraft 声音包。

构造函数

constructor(name: string, version: number = 1, description: string = "", author: string = "")

参数：

• name: 声音包名称
• version: 声音包格式版本（默认为 1）（如1.16.x为6，1.17.x为7）
• description: 声音包描述
• author: 声音包作者

方法

getMcmeta()

获取声音包的元数据信息。

返回值：

{
  pack: {
    pack_format: number, // 声音包格式版本（默认为 1）（如1.16.x为6，1.17.x为7）
    description: string
  }
}

getName()

获取声音包名称。

返回值：

string

createSoundsConfig(keys: SoundPackItem[]): SoundPackConfig

创建声音包配置。

参数：

• keys: 声音包项目数组

返回值：

返回 SoundPackConfig 对象，包含所有声音的配置信息。

setSound(value: Sound[])

设置声音列表，处理声音对象（如移除 .ogg 后缀）。

参数：

• value: 声音对象数组

返回值：

返回处理后的声音对象数组。

类型定义

Sound

interface Sound {
  name: string;         // 声音文件名
  volume?: number;      // 音量（默认为 1）
  pitch?: number;       // 音调（默认为 1）
  weight?: number;      // 权重（默认为 1）
  stream?: boolean;     // 是否流式播放（默认为 true）
  attenuation_distance?: number;  // 衰减距离（默认为 16）
  preload?: boolean;    // 是否预加载（默认为 false） 具体介绍可看Minecraft WIKI
}

SoundPackItem

interface SoundPackItem {
  keyValue: string;     // 声音键值
  category: Category;   // 声音类别
  replace?: boolean;    // 是否替换现有声音（默认为 true）
  subtitle?: string;    // 声音字幕
  sounds: Sound[];      // 声音数组
}

Category

声音类别可以是以下值之一：

type Category = "master" | "music" | "record" | "weather" | "block" | "hostile" | "neutral" | "player" | "ambient"

SoundPackConfig

interface SoundPackConfig {
  [key: string]: {
    category: Category;
    replace?: boolean;
    subtitle?: string;
    sounds: Sound[] | string[];
  };
}

示例

创建完整的声音包

import SoundPack from "soundspack-core";
import { Category } from "soundspack-core";

const soundpack = new SoundPack("音乐包");
const cig = soundpack.createSoundsConfig([
    {
        keyValue: "test",
        category: "record" as Category,
        sounds: soundpack.setSound([
            {
                name: "test"
            }
        ])
    },
    {
        keyValue: "test2",
        category: "music" as Category,
        replace: false,
        sounds: soundpack.setSound([
            {
                name: "test2"
            }
        ])
    }
]);
console.log(JSON.stringify(soundpack.getMcmeta(), null, 2));
console.log(JSON.stringify(cig, null, 2));

输出结果

{
  "pack": {
    "pack_format": 1,
    "description": ""
  }
}

{
  "yyb.test": {
    "category": "record",
    "replace": true,
    "subtitle": "",
    "sounds": [
      {
        "name": "test",
        "volume": 1,
        "pitch": 1,
        "weight": 1,
        "stream": true,
        "attenuation_distance": 16,
        "preload": false
      }
    ]
  },
  "yyb.test2": {
    "category": "music",
    "replace": false,
    "subtitle": "",
    "sounds": [
      {
        "name": "test2",
        "volume": 1,
        "pitch": 1,
        "weight": 1,
        "stream": true,
        "attenuation_distance": 16,
        "preload": false
      }
    ]
  }
}

注意事项

1. 声音文件名中的 .ogg 后缀会被自动移除，因为 Minecraft 会自动添加该后缀。
2. 声音包的键值会自动添加声音包名称的拼音首字母(经过replace(/[^a-z0-9]/g, '')处理)作为前缀，以避免冲突。
3. 默认情况下，声音会替换 Minecraft 中的现有声音，可以通过设置 replace: false 来改变此行为。

许可证

MIT

开源仓库

本项目由 小阿狼是也 开发，并托管在 Gitee 上。