NPC Music Player

Uses the Kits and GUI Announcements (optional) plugins from umod.org.

Current version: 1.2.6

As of version 1.2.6, no external NPC plugins are used, and we manage our own musician NPCs.  Keep this in mind and save your data files in case you need to go back to 1.2.5!

Playback converted midi files in ToneJs format. Ability to assign NPCs to each track including a single NPC on multiple tracks per song. NPCs are associated with a song by their band number and the type of instrument.

The NPCs must be assigned to a band number (1 - XX with 99 for Outpost), and must have a kit with either a held instrument or positioned within 1.5m of a mountable instrument and with allowsit set to true.

The ToneJs format converts midi to json format with information for track, notes and octave for each track along with other information. We can't use of what it provides such as control changes for pitch bending. This is not currently implemented into Rust instruments. Anyway, Rust is a game, not a DAW or MIDI sequencing app. So, this is a nice to have not an absolute requirement.

Hire NPCs where you stand to assign them to your band.

You may optionally spawn a band on the Outpost stage. This will be band 99.

Demo

Converter

You will need to convert your midi files to ToneJs format using our converter or this converter. There are other examples out there as well.

• Load NPCPlay onto your server (oxide/plugins directory).
• Open the converter link above.
• Drag and drop or select a multitrack MIDI file for conversion.
• The contents of a JSON-formatted song file will appear in the box below the upload button.
• You can preview the file in your browser if you like. However, this is nothing like the sound in-game.
• Copy this text and paste into a text editor.
• Save the file as songname.json. It is recommended that the name not contain spaces but it can contain underscores like "Back_in_Black.json"
• Depending on your OS, you may need to select All Files in the text editor when saving so that a txt extension is not added to the filename.
• Copy or move your new json song file to your Rust server into the oxide/data/NPCPlay/songs folder.
• Type /song list in game. If you do not see the file in this list, reload the plugin.

Permissions

The following permissions are used by NPC Music Player:

• npcplay.use => Allow user to run the /song, /band, /hire, and /movem commands

Configuration

{
  "Use GUIAnnouncements plugin for autostart bands: ": false,
  "AutoSpawn Outpost: ": false,
  "Outpost Band Trigger Start: ": false,
  "Outpost Band Trigger Stop: ": false,
  "Outpost Band Autostart: ": false,
  "Outpost Band Repeat: ": false,
  "Repeat Delay: ": 5.0,
  "AutoSpawn Outpost Song: ": null
  "Trigger Start/Stop Distance: ": 10.0,
  "Version": {
    "Major": 1,
    "Minor": 2,
    "Patch": 6
  }
}

The trigger start/stop settings determine whether the band will start playing when a player is in range or stop when they leave.

Commands

Many/most of these commands work best when used via the band gui (/band NUM gui):

• /song list = List songs in the data/NPCPlay/songs subdirectory

• /song load ID = Load a song (for use in previewing, showing info, etc.

• /song info = Show track info for loaded song

• /band list = List configured bands (group of NPCs and a song)

• /band ID gui = A graphical user interface for editing song track assignments for a band. THIS IS THE MAIN GUI YOU WILL WORK FROM.

• /band ID info = Show info for a particular band

• /band ID play = Start band number ID

• /band ID stop = Stop band number ID

• /band ID song ID = Add song with ID from song list to a band (NOTE THAT THIS HAS CHANGED)

• /band ID assign NPCID TRACKNUM = Add an existing npc with NPCID to a band, assigning to a specific track

• /band ID drum TRACKNUM = Setup a single track to be the drum track. There is special handling for octave on this track.

• /band ID tstart = Allow trigger start (NPC Enter, etc.)

• /band ID tstop = Allow trigger stop (NPC Leave, etc.)

• /band ID hire = Start or stop the hiring process. When active, you can select NPCs for your band by pressing "E" in front of each NPC.

These are definitely easier to use via the band GUI:

• /band musician select ID - Opens a GUI to edit the musicians for a band (ID) including name, assigned kit, and whether they can sit.

• /band musician name NPCID NEWNAME - Sets the name for a musician with id NPCID to NEWNAME

• /band musician cansit NPCID - Toggles the status of whether or not the musician with id NPCID can sit

• /band musician remove NPCID - Compltely removes this musician

• /band musician selkit NPCID - Opens a gui to select the kit for the musician with id NPCID

• /band musician kitsel NPCID KITNAME - Sets the kit variable for the musician with id NPCID to KITNAME, and also issues the kit to them.

• /hire = If already in hire mode for a band, spawn a new musician. Otherwise, do nothing...

• /movem = If already in move mode for a musician, move them to your current location.

• /movem NPCID = Start moving the musician with this ID

Band Setup (with GUI)

• You will need to, using the Kits plugin, create kits that include the desired instrument. Do not include more than one held instrument in the tool belt of the kit.

• Type /band new and then /band list. You should see a new BANDID number.

• Type /song list and note the SONGID of the song you wish to have this band play.

• Type /band BANDID song SONGID

• Type /band BANDID gui

• Click the "Hire" button at the upper right

• Move to each positition where you want to spawn a musician and type /hire. A new basic player model should spawn there.

• Type /band BANDID gui

• Click the "Musicians" button at the lower right

• For each musician, enter a new name (NO SPACES) if desired and press enter. Click each button below "Select Kit" to apply a kit to each musician. Finally, click the buttons below "Can Sit" for each musician you want to be able to sit. This last step is critical for piano, drums, and xylophone.

  • (pro-tip) If you are having trouble typing a full name in the musician or band name boxes in the GUI, type those in full into a text editor and then copy and paste them into the editor.

• Once you have all your new NPCs in place, clothed, seated and/or holding instruments, close the Musicians menu.

• The track listing for your song will show in rows from top to bottom.
• Your musicians will be listed left to right at the top. They will also appear at the bottom in red. This means that they have not been assigned.
• At the far left you can select a drum track. Hopefully, the names of the tracks just to the right will work as a guide.
• At any time you can push play, stop, or close.
• Change assignments while playing if you wish.

Band Setup (without GUI)

REWORK IN PROGRESS - please use the GUI:

• Type /band new and then /band list. You should see a new BANDID number. This will need to be assigned to your NPCs.
• You will need to create NPCs. Place them in position on a stage setup or wherever you like.
• For NPCs to be seated at drums or piano, etc., /npc_edit NPCNAME and then type /npc allowsit true. If they are close enough, they should sit down.
• Place your guitar and bass NPCs wherever you like. You will need to, using the Kits plugin, create kits that include the desired instrument. Do not include more than one held instrument in the tool belt of the kit.
• Set the band for each NPC to match the BANDID number, e.g. /npc_edit NPCNAME and then /npc band 1.
• Once you have all your new NPCs in place, record the ID numbers assigned to them.
• Type /band new
• Type /song list and note the SONGID of the song you wish to have this band play.
• Type /band BANDID song SONGID
• For each band member NPC:
  • Decide which track or tracks they should play.
  • For example, track 1 is listed as bass.
  • /band BANDID assign NPCIDofBASSNPC 1.
• If you have a drummer and a drum track, you will need to assign the drum track for the song in addition to assigning an NPC.
  • /band BANDID drum TRACKNUM (default will be 0, which may or may not be the right track.
• You can assign a single NPC to multiple tracks if you like. Just repeat such as:
  • /band 1 assign 784132124 2
  • /band 1 assign 784132124 4
• Once you have your band setup, you can type /band BANDID play
• Type /band BANDID stop to stop playback.

Requirements and Limitations

• Some MIDI files may include notes that are out of the range of some Rust instruments. Piano has the most range but others are limited to typically 1-2 octaves.
• Correction for this currently must be done in the MIDI file itself. Or, for the brave, you can edit octaves for each note in the json file. This is NOT recommended but can be done.
• We do currently correct drum tracks.
• NPCs using a held instrument such as guitar or bass will need a kit via the Kits plugin which includes the desired instrument and no other held instruments.
• NPCs playing piano, drums, or xylophone must be positioned close to the instrument and have the allowsit variable set to true. They need to be closer to the desired instrument than any other seated instrument or chair, etc.
• The default server maxtickspersecond of 300 should work - lower or higher values may not.

For Developers

Hooks have been implemented to allow other plugins to interact with this one:

Start band playback. tstart for band must be set to true.

	BandPlay(int bandnum)

Stop band playback. tstop for band must be set to true.

	BandStop(int bandnum)

For the calls below, note that the plugin will keep track of created bands and musicians. You should not ever need to recreate or respawn bands or musicians separately. However, if you want to manage them yourself to ensure they do not reload when no longer needed, you must delete them yourself. Users of the plugin will also be able to see them, although this access typically should not be handed out to anyone other than a server admin.

Create a new band, optionally passing a bandid. Use numbers above 99 to avoid conflict with native bands.

	private int CreateBand(int id = 0)

Remove/delete a band

	private bool RemoveBand(int id)

Return or set band info (BandData class)

	private object GetBandInfo(int bandid)

	private void SetBandInfo(int bandid, object data)

	public class BandData
	{
		public int id;
		public string name;
		public string song;
		public bool autostart = false;
		public bool repeat = false;
		public bool npcTriggerStart = false;
		public bool npcTriggerStop = false;
		public int drumtrack;
		public Dictionary<int, ulong> channels = new Dictionary<int, ulong>(32);
		public Dictionary<int, string> description = new Dictionary<int, string>(32);
	}

Return or set musician info (MusicianInfo class)

	private object GetMusicianInfo(ulong npcid)

	private void SetMusicianInfo(ulong npcid, object data)

	public class MusicianInfo
	{
		public int band;
		public string displayName;
		public Vector3 position;
		public Quaternion rotation;
		public string kit;
		public bool allowsit;
	}

Spawn a musician object with given name at desired position and rotation for a band. Returns the NPC userID

	private ulong SpawnMusician(string name, Vector3 position, Quaternion rot, int band, ulong olduserid=0)

Give a musician object an item in wear, belt, or main containers. If loc == "kit", pass a kit name for the Kits plugin.

	private void GiveMusician(ulong musid, string itemname, string loc = "belt")

Check if a player object is a musician.

	private bool IsMusician(BasePlayer player)

Kill a musician by passing its player object.

	private void KillMusician(BasePlayer player)

TODO

• Auto assigning of NPCs based on held instrument, etc.
• Repeat
• Multiple songs per band
• Spawning of bands based on the chosen song.

$25 US