KivalEvan
Beat Saber JS Map
General-purpose Beat Saber beatmap scripting library with TypeScript, fully-typed schema and flexible tool to ease scripting development surrounding beatmap.
It is designed to be simple and familiar with traditional scripting with barely hidden layer of abstraction. It is optimised for speed with minimal compromise allowing for faster work iteration.
[!WARNING]
API changes, structural changes, or game updates that require restructuring may result in breaking changes in future update. Many work has been placed in order to minimise the breakage on minor version update.
Features
- Latest Schema: Supports all official schema including modded features.
- Supported version: v4.1.0, v3.3.0, v2.6.0, v1.5.0.
- Version-agnostic Wrapper: Readable and cross-version core allows for seamless version transferring.
- Partial Creation: Define beatmap object partially and let default fill the rest of fields.
- Mod Compatible: Chroma, Cinema, Noodle Extensions, and Mapping Extensions is supported out of
the box.
- Helpers are available in main for essentials such as getting modded position.
- Class method may contain function parameter to access any arbitrary data.
- Tree-shakeable: Modularity approach minimise build size.
- Built-in Utility: Relevant utilities including math, colour, easings, and more.
- Validator & Optimiser: Customisable tool ensuring beatmap schema is valid to the game and optimised for storage.
Prerequisite
- Any TypeScript supported runtime/transpiler
- Deno
- Bun
- Node.js
- Vite
- Basic JavaScript or TypeScript knowledge
- Module is entirely TypeScript, but for common use case you do not need an in-depth knowledge.
Getting Started
Before you start, you may want to understand how Beat Saber stores the beatmap data here.
You may get this package from NPM or JSR using respective package manager.
To get scripting, simply create a .ts file anywhere, preferably inside map folder for simpler
setup, import module via module specifier or package manager, and then run the script. That's it. Do
check out the the guide for usage detail.
Importing/Runtime
This is for beginner on how to import library and use the script. Importing bsmap into script file
can be done in various ways, it is recommended that you run the command in the same folder as the
script file.
Deno
// Choose one of the four ways, prioritise top to bottom
import * as bsmap from 'jsr:@kvl/bsmap';
import * as bsmap from '@kvl/bsmap'; // via `deno add bsmap`
import * as bsmap from 'npm:bsmap';
import * as bsmap from 'bsmap'; // if previously used NPM `package.json` exist
// Run command: `deno run script.ts`Bun
// via `bun add bsmap`
import * as bsmap from 'bsmap';
// Run command: `bun script.ts`Node.js & Browser NPM (ESM)
// via `npm install bsmap`
import * as bsmap from 'bsmap';
// Run command: `ts-node script.ts`
// Refer below for browserNode.js NPM (CJS)
// via `npm install bsmap`
const bsmap = require('bsmap');
// Run command: `ts-node script.ts`Once you've imported the library, you can try the bare minimum example:
const data = bsmap.readDifficultyFileSync('ExpertPlus.beatmap.dat', 4);
// ... arbitrary code
bsmap.writeDifficultyFileSync(data, 4);You may also clone the library to store and import locally, and make any modification as you wish.
If you are using the script outside of the map directory, you can specify the map directory without
the need to explicitly apply directory on IO function. This can be any valid directory as long as
it points to directory. If directory is explicitly written in IO function, then that will instead be
prioritised.
// you should always use absolute path for this,
// otherwise it will try to resolve path with your CWD
bsmap.globals.directory = '/PATH/TO/YOUR/BEAT_SABER/MAP_FOLDER/';Runtime
Module uses respective vendor API for filesystem and path functionality to handle read and write
module, currently supporting Deno, Bun, and Node.js. This may also work on other runtime given that
node: built-in module is available on import, otherwise you may be required to provide the
following fs and path functionality in shims module.
Browser
As it is written in TypeScript, you may need transpiler such as tsc or vite that will compile
down to single JavaScript file to be able to be used on browser, depending on build option down to
ES5 support.
Typical browser do not have filesystem functionality and thus read and write module may not work
as expected. You may use load and save which can read from web input.
Development
Deno is used for development, simply install and setup workspace, no other setup is required to get started as it provides necessary toolchain.
If you wish to contribute, do follow the guidelines. Make pull request for feature addition/enhancement/fix or create an issue if you encounter error/problem or want an improvement.
Guidelines
Styling & Documentation
- Use
deno fmtfor standard formatting- Do not change
deno.jsonconfiguration
- Do not change
- File names shall use camel case
- Exported types, interfaces, fields, and functions should be accompanied by JSDoc comment right
above its definition
- Function/method should provide usage example
- Interfaces that are exposed to user must use
Iprefix to indicate interface rather than instantiable object.
Coding
- Top-level function shall use regular function
- No dependencies shall be used outside of examples, extensions, and tests
- Vendor dependency is allowed so long it gracefully handles every platform possible
- Prefer
typesover concrete type for parameter/return type- Use generic if necessary
- Use ESM
- Avoid circular imports
- Avoid URL imports
- Avoid default export
- Prefer
node:built-in import if needed
Planned
- Write JSDoc on every important bit
- Separate class method to own function
- Add more helper for Chroma and Noodle Extensions
Known Issue
- As beatmap module here is version agnostic, certain data such as bomb direction, info set custom
data, etc. are either renamed, restructured or unavailable.
- Certain beatmap version do not contain certain information in schema and are therefore not present in-game.
Credits & References
- HSV conversion algorithm
- CIE-L*ab and Delta E2000 algorithm
- Uninstaller and Qwasyx (improving it) for note swing detection algorithm
- Top_Cat for math guidance
- Others for helpful feedback & indirect contribution