Project Heartbeat

Project Heartbeat

Not enough ratings
Editor Manual
By EIREXE
In this official guide you will learn how to create your own songs using the built-in editor, and how to upload your creation to the Steam workshop!
   
Award
Favorite
Favorited
Unfavorite
Introduction
This is the official manual for the Project Heartbeat song editor, if you need any help or have any question please join our official discord, we don't bite: https://discord.com/invite/qGMdbez

This guide only covers the technical aspects of how to use the editor, for information on note placement, music synchronization etc please check the COMMUNITY CHARTING GUIDE
Pre-requisites
Before we start, we will need a few things

  • A song audio file or a youtube URL that the game can use to download that song, if you plan to upload your song to the workshop only songs with YouTube URLs as audio sources are permitted.
  • A preview image for the song, preferably as a 512x512 image (for uploading to the workshop the max file size is 1 MB)
  • A copy of project heartbeat
  • Some free time

Here's an example preview image and how it appears in the game:


Creating our song and inserting metadata
Creating the song

Project Heartbeat songs are comprised of the song itself and a series of charts.

In order to create our song we will go to tools -> song editor:



Once we are there, we can click on the new song button



Inserting metadata

Afterwe have created our song, it's time to insert the song's metadata, you can do this by selecting the song and clicking on the edit song data button



A new window will open, there you can find a series of tabs, each tab is fairly important they are, in order:

  • Metadata: Basic song data such as the song's title, the author, etc...
  • Techincal data: In this section you can set the data that affects how the song is played.
  • Charts: This allows you to enable and disable charts of the three built-in difficulties.
  • Graphics: This section is used to set the visual aspects of the song, such as the background image, the preview image and some other information.




In the technical data tab, we must set our BPM (this is very important, as some aspects of the game depend on BPM, the value we input here will be the base value inside the song, but you can change it with BPM change events, more on that later) and in our case, we will use a youtube video as the source for our audio, although we have chosen not to use it as a video background.



You can ignore the charts tab for now.

We will finally set our preview image in the graphics tab and hit okay.




Now that we are done with the metadata, we can now create a new chart for us to edit, for this we will select our song and click on add chart. On this dialog we can set our difficulty (we recommend using one fo the built-in ones for consistency, but you can use a custom one if you want) and with how many stars it will be displayed (stars denote how difficulty the chart is)


Editing our chart
In order to edit our song, we will be selecting our chart and clicking on okay, if you've selected a youtube video as an audio or video source you will be asked to download it.




We are finally in the editor, we can now create our chart!


Here's a very basic rundown of the editor interface:



  • General utilities: Contains some useful things, such as automatic note arrangement tools, the ability to hide and show layers, and some other tools such as the slide chain creation tool or the PPD and Guitar Hero/MIDI importers.
  • Timeline: The timeline is where you will place your note's timing, you can move around the timeline using the seek bar over it or by holding the middle mouse button and dragging, you can also zoom in and out using control and the + and - buttons or control+scrollwheel.

    You can create new notes by double-clcking.
  • Timeline grid settings: Allows you to set the timeline's subdivisions, as well as the offset, this is useful for timing.
  • Inspector: This is what you can use to edit the properties of any note, more on the specifics of that later.
  • Game grid settings: You can use this to set the subdivisions in the game's playing area.
Editor tips & tricks
Arrangement tools





You can select (by using shift+clicking or clicking and dragging) notes in the timeline and have the editor arrange them either vertically, horizontaly, diagonally or by angle, the first note to be used will be the earliest one.

Creating multi-notes




Multi-notes or simultaneous notes are notes that happen at the same time, canonically multi-notes have different stats (they travel slower and usually in a straight line) so the editor will automatically set those values for you, this can be disabled by unchecking the auto-multi option.

Creating slide chains




Slide chains are slide notes that you have to hold, they can be created using the tools in the tools tab.


Importing timing from other sources



Normally when creating a chart you will first place your note timing and then position the notes on screen, for convenience Project Heartbeat allows you to import from MIDIs, this includes an option for guitar hero specific midis (they are a bit special, as they encode all difficulties in a single file), however new importers will be released eventually for Clone Hero and osu! charts.

Creating simultaneous slides in the same direction



Two extra layers can be enabled in the layers tab, these allow you to place slide notes facing the same diirection.

Creating extended notes



You can create extended notes by opening the contextual menu, you can do this by right clicking the note while having it selected.

Re-doing the sync for your chart



Sometimes you might want to move all notes in the song because you've changed audio sources and they now don't sync properly.

To facilitate this, PH includes a "Chart Offset" tool, here you simply enter the offset in milliseconds and press apply offset to apply it (you can control-z to undo if you don't like the result)
Note property rundown
Notes have many properties, they can be seen and modified in the inspector, it is important to familiarize yourself with what each of these do.



  • Position: The position in the playing area of the target of the note.
  • Time: The time where the note ends (the point where the user will hit the note if they do it perfectly).
  • Distance: How much the note travels from its starting point to the target.
  • Time out: The time it takes the note to travel from its starting point to the target.
  • Auto time out: If enabled, the time out will be set automatically based on BPM.
  • Oscillation amplitude: The amplitude of the sine wave the note follows when moving, more info[www.ck12.org] (set this to 0 for a straight path).
  • Oscillation frequency: The frequency of the sine wave the note follows when moving, more info[www.ck12.org]. (set this to 0 for a straight path).
  • Hold: If this is a hold note.
  • Angle: At what angle will the note come from. (You can also change this by clicking anywhere in the field with a note or notes selected).
Expression runner

Since 0.4.0 a new expression runner option is available in the engine, this allows you to use math to automate changing of note properties (remember when you used functions in school math to plot graphs? This is the same).

The output dropdown allows you select what property will your value be assigned to, inside the expression runner you can write your expressions.

You can access each selected note's properties by doing note.property, the following properties are available:

  • position (This is a vector2, use .x and .y to access coordinates)
  • vime_out
  • entry_angle
  • oscillation_amplitude
  • oscillation_frequency
  • distance
  • end_time (sustains only)

In order to construct a Vector (such as position's) you can simply do Vector2(x, y).

Here are all the available Vector2 methods and properties: https://docs.godotengine.org/en/stable/classes/class_vector2.html
Uploading to the workshop and updating your song



Uploading to the workshop is very simple, simply select the song in the editor's song selection dialog and click upload to workshop, if your song doesn't have any issues that need resolving beforehand you will be greeted with a window where you can input some of your basic data.





After accepting the conditions stated and clicking upload, you wil be redirected to your song's workshop page, if you haven't accepted the steam workshop ToS you will be asked to, from your workshop page you can edit more data, add a video preview, screenshots etc...




Also please ensure you set your song to be visible to everyone, else no one will be able to play it.

Sharing songs outside the worskhop


If you decide to share your song outside of the Steam Workshop for whatever reason, simply go to the main menu -> tools and open the songs folder, there you can find your song, simply give this folder to your mate and then can install it by copying it into their own songs folder.
Shortcuts
Name
Shortcut
Test play
Z
Test play (at time)
X
Angle flip
C
Vertical flip
Page Down
Horizontal flip
Page Up
Autoarrange
Numpad 1-9
Set angle
Control+Numpad 1-9
Change circle size
Numpad + and -
Set circle inside flag
Numpad /
Circle clockwise
Numpad +
Circle counterclockwise
Numpad enter
6 Comments
EIREXE  [author] Dec 19, 2023 @ 2:33pm 
@konerini Correct, ever since lino did the editor revamp, the new engine port will come with a link to the renewed docs at https://ph-editor.eirteam.moe/
konerini Dec 19, 2023 @ 10:59am 
Apparently, you no longer have to specify BPM. At least, I don't have this setting when adding a song.
fizzyflask3@twitch.tv Jul 24, 2022 @ 9:11pm 
@handsoap in order to put a chart onto the workshop it needs a link to a youtube video. which means it has to be posted on youtube by someone who has permission for the song or copyright free music. Generally if you can find it on youtube its good. but for the purpose of livestreamers that play this game it would be good for a chart maker to state if the song is prone to copyright strikes but again not required. just nice to do.
EIREXE  [author] Dec 25, 2021 @ 10:10am 
@nexocentric obviously freely licensed songs are prefered, but afaik there's no way to check for me
nexocentric Dec 25, 2021 @ 8:10am 
I have a question about licensing and copyright as well? Is it best for a song to have a creative commons copyright (like TheFatRat does with his songs)? Is a CC license something you can check for via YouTube? A little bit more information around this area would be appreciated.
handsoap Apr 4, 2021 @ 9:35pm 
Can this be done with any song? No licensing or copyright bullshit to worry about?