SEGAy/Chunithm-Research
1
0
Fork 0
mirror of synced 2024-11-23 22:30:57 +01:00
Code Releases Activity

reformat document layout, add more stuff

Browse Source
This commit is contained in:
Nova 2021-05-21 03:25:31 -04:00
parent d110b5ce38
commit dc03967f83
6 changed files with 447 additions and 322 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
.gitignore vendored Normal file
View File

@ -0,0 +1 @@
*.code-workspace

324
Charting.md Normal file
View File

@ -0,0 +1,324 @@
This is a general documentation on the chart files used in the game. These files indicate the structure of the song, such as note placement and tempo.
# Things to know
* Most counting in this file format starts from 0. A measure of 0 means at the beginning of the song, a cell of 0 means the first cell on the left, etc.
* The location for chart files can be found in ``root¥app¥data¥AXXX¥music¥musicXXXX``. The file format for charts is ``.c2s``, and are plain text files that can be opened in tools like Notepad++.
* A cell is the corresponding key for the note on the playfield. The playfield has 16 columns, numbers from 0-15 from left to right.
* A measure is a function of time containing a specific amount of beats. Each measure usually contains 4 beats, and stays relatively consistent throughout the song.
# Tags
## **BPM**
Designates the BPM for the specified measure of the song.
### Schema:
| Beginning Measure | Offset | BPM |
| ---- | ---- | ---- |
## **MET**
Designates the time signature for the specified measure of the song.
### Schema:
| Beginning Measure | Offset | Second Value | First Value |
| ---- | ---- | ---- | ---- |
It is very important to note that the values for the time signature are in reverse. It is also worth mentioning that this is purely cosmetic. The only thing that this value will affect is the placement of the thin measure lines on the playfield.
## **SFL**
Designates the speed of the playfield at the specified measure of the song.
### Schema:
| Beginning Measure | Offset | Duration | Multiplier |
| ---- | ---- | ---- | ---- |
It is important to note that the multiplier must have an accuracy of 0.000001, meaning that it should have six digits after the decimal point. This value will multiply the player's current playfield speed, so notes will appear faster or slower based on this value. This value is purely cosmetic, and will not affect the placement of notes in the .c2s file, only the player will see a difference. This value can also be made negative, which will result in the board moving in reverse, usually used for aesthetic purposes such as [this section of Fracture Ray's MASTER chart](https://youtu.be/5m7bMyIDoec?t=48).
# Notes
## Universal Note Schema
| Note Type | Measure | Offset | Cell | Width |
| ---- | ---- | ---- | ---- | ---- |
### **Note Type**
A note type is the type of note that you want to be placed at this particular point. There are various types of notes that can be used, and most of them will have additional variables that will be appended to the end of the typical schema. There will be more information later on explaining each of these notes.
#### **Note Types:**
* TAP (tap)
* CHR (ex-note)
* HLD (hold)
* SLD (slide)
* SLC (slide control point)
* FLK (flick)
* AIR (air)
* AUR (air up-right)
* AUL (air up-left)
* AHD (air hold)
* ADW (air downwards)
* ADR (air down-right)
* ADL (air down-left)
* MNE (mine)
### **Measure**
The measure is the specific measure that you want the note to be placed in. Each measure is (usually) 4 beats. The value starts from 0 and continues infinitely, although should always end with the song.
### **Offset**
A function of time to show how offset a note or timing point should be from the measure. This relies on the resolution of the song, designated by the RESOLUTION tag. The full resolution is an entire measure, so with a resolution of 384, the first beat of a measure would be 0, the second would be 96, the third would be 192, the fourth would be 288. To get the desired beat, divide the resolution by 4, multiply it by the beat that you want, and then subtract it by the resolution divided by 4.
For a fraction of a beat, divide the resolution by 4, then multiply it by the fraction of the beat you want. Then add that result with the desired beat.
The function for this would be:
```b(r/4)-(r/4) + f(r/4)```
where b is the desired beat rounded down to a whole number, r is the resolution of the song, and f is the fraction of the beat.
For example, if I wanted a note on the 2 1/2th beat of a 4 beat song with a resolution of 384, I would perform the following:
```
2(384/4)-(384/4) + 1/2(384/4)
192 - 96 + 48
144
```
### **Cell**
As stated above, the cell is the numerical ID for the column in the playfield that the note should appear in. Note that this value should be the column that the note first appears in **from the left**.
### **Width**
Separate from the Cell value, the Width value notes how wide the note should be, extending from the value listed in Cell to the right. The minimum value is 1, which means that the note only occupies the column listed in cell. As an example, a width of 3 on a note with a cell value of 7 would have the note occupy columns 7, 8, and 9.
## Additional Note Values
Most note types require additional information to function correctly. This section will provide an example of the schema that the note uses, followed by an explanation for any values not included in the universal schema. Any values in quotes indicate a value that is consistent with that note.
### **Tap**
Tap notes are the most basic notes that can be charted. They simply require the player to hit the cell that the note occupies at the required time.
#### Schema:
| "TAP" | Measure | Offset | Cell | Width |
| ---- | ---- | ---- | ---- | ---- |
Tap notes do not differ from the universal schema listed above.
### **Ex-Notes**
Ex-Notes are similar to tap notes, although they give the player more score for hitting them accurately.
#### Schema:
| "CHR" | Measure | Offset | Cell | Width | Unknown |
| ---- | ---- | ---- | ---- | ---- | ---- |
* Unknown: Seems to always have a value of "UP" or "CE".
### **Hold**
Hold notes are similar to tap notes, but require the player to keep the designated cell pressed over a continuous period of time.
#### Schema:
| "CHR" | Measure | Offset | Cell | Width | Duration |
| ---- | ---- | ---- | ---- | ---- | ---- |
* Duration: The amount of time that the note needs to be held down for. This value is based on the same format for offset.
### **Slide**
Slide notes are similar to hold notes, but are capable of moving between cells while sustaining the hold. There are two types of slide notes, SLD and SLC. Slides that start with a straight line begin with an SLD, while slides that start immediately with movement start with an SLC. All slides end with an SLD note.
#### Schema:
| "SLD"/"SLC" | Measure | Offset | Cell | Width | Duration | End Cell | End Width |
| ---- | ---- | ---- | ---- | ---- | ---- | ---- | ---- |
* Duration: The amount of time that the note will take to move to the target cell. This value is based on the same format for offset.
* End Cell: The column that the slide will move towards over the duration of the slide. Similar to the Cell value, this value will be where the left side of the cell is, and can be anywhere from 0-15. To have a slide that stays straight over the duration, make the End Cell value the same as the Cell value.
* End Width: The width that the slide will have at the end of the duration. Similar to the Width value, this value can be anywhere between 1-16. If the End Width differs from the original Width, the slider will gradually shrink or expand in width over the course of the slide.
A slide will not end until you call an SLD in the same cell that another slide is in at that moment in time. To adjust a slide without interrupting it, use SLC.
The feature of sliders shaking from side to side rapidly is not a built-in function of the game, it instead simply involves having the slider move left and right a few cells on very short offsets.
### **Flick**
A flick note involves the player having their finger within the cells that the flick inhabits, and then swiping to the left or the right depending on which direction the flick has.
#### Schema:
| "FLK" | Measure | Offset | Cell | Width | Direction |
| ---- | ---- | ---- | ---- | ---- | ---- |
* Direction: The direction that the user is meant to swipe in. The possible values are "L" for left and "R" for right.
### **Air**
An air note involves the player raising their hands through the IR sensors above the physical keyboard. Unlike other notes, these notes act as modifiers for already existing notes. There are also different cosmetic versions of the note, however they each function identically.
#### Schema:
| "AIR"/"AUR"/"AUL" | Measure | Offset | Cell | Width | Target Note |
| ---- | ---- | ---- | ---- | ---- | ---- |
* AIR/AUR/AUL: Each of these note types are identical functionality-wise, although affect the appearance of the arrow above the note. AIR has an upwards arrow, AUR has an up-right arrow, and AUL has an up-left arrow.
* Target Note: This value designated what note the Air note "leeches" off of. You should have this note be in the same cell, measure, and offset as the Air note. It's also recommended to only use this note at the end of a note, rather than in the middle of a sustained note. This recommendation can be discarded for high-level charts.
## **Air Hold**
An air hold note involves having the player hold their hands up towards the sensor after performing an air note. Air holds will always end with a mid-air downwards note automatically.
#### Schema:
| "AHD" | Measure | Offset | Cell | Width | Target Note | Duration |
| ---- | ---- | ---- | ---- | ---- | ---- | ---- |
* Target Note: This value designated what note the Air note "leeches" off of. You should have this note be in the same cell, measure, and offset as the Air note. It's also recommended to only use this note at the end of a note, rather than in the middle of a sustained note. This recommendation can be discarded for high-level charts.
* Duration: The amount of time that the note will take to move to the target cell. This value is based on the same format for offset.
To have mid-air downwards notes in a sustained air note, make the first air hold note last until the point where the mid-air note would be, then add another air hold note that starts at the same offset where the preceeding air hold note ends.
### **Downwards**
A downwards note involves the player lowering their hands through the IR sensors above the physical keyboard. Unlike other notes, these notes act as modifiers for already existing notes. There are also different cosmetic versions of the note, however they each function identically.
#### Schema:
| "ADW"/"ADR"/"ADL" | Measure | Offset | Cell | Width | Target Note |
| ---- | ---- | ---- | ---- | ---- | ---- |
* ADW/ADR/ADL: Each of these note types are identical functionality-wise, although affect the appearance of the arrow above the note. ADW has a downwards arrow, ADR has a down-right arrow, and ADL has a down-left arrow.
* Target Note: This value designated what note the downwards note "leeches" off of. You should have this note be in the same cell, measure, and offset as the downwards note. It's also recommended to only use this note at the end of a note, rather than in the middle of a sustained note. This recommendation can be discarded for high-level charts.
### **Mines**
A mine note involves the player not touching the cell that the mine is placed on. Touching the cell will result in the player losing score and possibly failing the track.
| "MNE" | Measure | Offset | Cell | Width |
| ---- | ---- | ---- | ---- | ---- |
Mine notes require the same information as Tap notes, and simply follow the universal schema mentioned above.
# Demonstration
Below is an excerpt from the .c2s file for Cyaegha's MASTER difficulty, which has a RESOLUTION of 386.
```
TAP 8 0 6 4
TAP 8 0 12 4
SLC 8 96 4 4 7 3 4
TAP 8 96 10 4
SLC 8 103 3 4 10 2 4
SLC 8 113 2 4 13 1 4
SLC 8 126 1 4 22 0 4
SLD 8 148 0 4 236 0 4
TAP 8 192 8 4
SLC 8 288 6 4 4 7 4
SLC 8 292 7 4 12 9 4
SLC 8 304 9 4 9 10 4
SLC 8 313 10 4 12 11 4
SLC 8 325 11 4 23 12 4
SLD 8 348 12 4 36 12 4
AHD 9 0 0 4 SLD 192
CHR 9 0 4 8 CE
AIR 9 0 4 8 CHR
AHD 9 0 12 4 SLD 192
TAP 9 288 3 4
TAP 9 288 9 4
```
Below is what the gameplay for this section looks like. This will be broken down into each line of the .c2s file to see their corresponding patterns in gameplay.
![Demonstration of Cyaegha Excerpt](https://raw.githubusercontent.com/Suprnova123/Chunithm-Charting-Research/main/_assets/cyaegha%20example.gif)
The two tap notes at the beginning appear as:
```
TAP 8 0 6 4
TAP 8 0 12 4
```
The order of values in these lines is the following:
``Tap note | on the 8th measure | with an offset of 0 | starts on cell 6/cell 12 | extends 4 cells to the right``
You can tell that these notes are supposed to occur at the same time because the share the same measure and offset. Remember that the cells are labelled as 0-15, meaning that the first cell on the left is cell 0.
The next two notes are a slide and a tap that occur at the same time. These appear in the document as:
```
SLC 8 96 4 4 7 3 4
TAP 8 96 10 4
```
Note that the slide has the note type of SLC, since the slider starts in motion. If the slider was stationary at the beginning, it would've had an SLD note type.
The order of values for the slide note is the following:
``Slide note | on the 8th measure | with an offset of 96 | starts on cell 4 | extends 4 cells to the right | has a duration of 7 resolution | ends on cell 3 | ends with a width of 4``
There are a few important things to note here. For one, with a measure of 8 and an offset of 96, this means that the note happens on the second beat of the 8th measure (remember, an offset of 0 means the first beat). It also has a very short duration, at only 7 resolution. This means that the slider only lasts for almost 2/100th of a measure. The reason it's so short is because it's designed to look like a curve. There are later SLC notes that attach to the first slider that gradually change to the shape to a curve.
The tap note later on has an order of values of:
``Tap note | on the 8th measure | with an offset of 96 | starts on cell 10 | extends 4 cells to the right``
Again, since the two notes occur at the same measure and offset, they are simultaneous.
The next notes are several control points for a slider, as well as creating a new slider, and a tap note. Their lines are:
```
SLC 8 103 3 4 10 2 4
SLC 8 113 2 4 13 1 4
SLC 8 126 1 4 22 0 4
SLD 8 148 0 4 236 0 4
TAP 8 192 8 4
SLC 8 288 6 4 4 7 4
SLC 8 292 7 4 12 9 4
SLC 8 304 9 4 9 10 4
SLC 8 313 10 4 12 11 4
SLC 8 325 11 4 23 12 4
SLD 8 348 12 4 36 12 4
```
There are several important things to note here. For one, the SLCs at the top are within very quick succession of each other. As stated above, this is because it's creating a curved slider, so it's very precise to look smooth. There is also an SLD immediately after it, which has a duration of 236 resolution. This is important because you can see that this slider is supposed to end at the same time as the other slider. If you add together the offset, which is 148, and the duration, you'll get a value of 384. If you add together the offset and duration of the second SLD at the bottom, you also get 384. Since they are both on the same measure, this shows that they will end at the same time as each other. It's also worth mentioning that the second pair of SLCs are not related to the first pair. They start on a separate cell from the other slider, so it creates a new slider instead of extending a previous one.
The final part of the excerpt contains several air notes, an air hold, an ex-note, and several tap notes. These appear in the file as:
```
AHD 9 0 0 4 SLD 192
CHR 9 0 4 8 CE
AIR 9 0 4 8 CHR
AHD 9 0 12 4 SLD 192
TAP 9 288 3 4
TAP 9 288 9 4
```
You'll notice that both AHDs, the AIR, and the CHR notes all start at the same time, since they share the same measure and offset. Let's break down each note.
The AHD notes represents the following:
``Air hold note | on the 9th measure | with an offset of 0 | starts on the 0th cell/12th cell | extends to the right by 4 cells | leaches off of the Slider note that occupies that same cell | has a duration of 192 resolution``
The CHR note represents:
``Ex-note | on the 9th measure | with an offset of 0 | starts on the 4th cell | extends to the right by 8 cells | CE modifier``
The AIR note represents:
``Air note | on the 9th measure | with an offset of 0 | starts on the 4th cell | extends to the right by 8 cells | leaches off of the ex-note that occupies the same cell``
The excerpt finally ends with two TAP notes, which mean the following:
``Tap note | on the 9th measure | with an offset of 288 | starts on the 3rd/9th cell | extends to the right by 4 cells``
This concludes the analysis of this excerpt of Cyaegha.

3
DISCLAIMER Normal file
View File

@ -0,0 +1,3 @@
This document does not condone the illegal piracy, operation, modification, or reverse engineering of CHUNITHM arcade games, nor any games licensed by Sega, as such actions may violate Japanese and international law.
"CHUNITHM" is a trademark of SEGA Corporation. "Arcaea" is a trademark of Lowiro Limited. All referenced songs belong to their respective copyright holders.

22
General.md Normal file
View File

@ -0,0 +1,22 @@
This is a list of general information that should be known regarding Chunithm's file format, as well as this collection of research. This includes a list of files of interest, the general overview of them, and links to additional documentation if available, as well as meta information about this research document.
# Meta
* Chunithm makes frequent use of ``.xml`` files. This document will, for the sake of simplicity, assume that you understand the basic format of ``.xml`` files.
* References to "music" and "song" will refer to the files in the ``music`` folder, which includes ``Music.xml``, as well as the chart files. References to ``audio`` will refer to the files in the ``cueFile`` folder.
# Folders
Chunithm's method of receiving updates involves storing the new information in separate "AXXX" folders, found in ``root¥app¥data``. These folders will have varying numbers replacing the Xs depending on the update. Any references to "AXXX" in this document will refer to an unspecified ``A`` Folder. It is worth noting that, while songs usually have their complementary files (audio, jackets, rights) in the same ``A`` folder, it is possible that they are also in other folders. At the moment, it is assumed that newer AXXX folders will overwrite the older AXXX folders' data in terms of being in-game, although the older files will remain intact, however this is not confirmed. It is worth noting that Chunithm's updates will regularly remove certain songs that were prexisting, usually from rights expiring. It is also worth noting that the major updates for Chunithm that change branding and add new features (for example, Amazon to Crystal, or Crystal to Paradise) will not involve new AXXX files, instead condensing them all into the A000 folder. The .exe in ``root¥app¥bin`` may also be overwritten, among other binaries.
# File Types
This is a list of file types of interest, the locations of them, and links to additional info if necessary. This is **not** an extensive list, some files that are not of interest will not be included.
## Audio Files
Audio files for music are found in ``root¥app¥data¥AXXX¥cueFile¥cueFileXXXXXX``. The ID of the cueFile can be found in the XML ``<cueFileName>`` tag of the ``Music.xml`` file in the same folder as the chart files for the song of interest. More often than not, these files share the same ID as their corresponding music ID. These files are encoded in the proprietary [CRIWARE ADX2 audio format](https://en.wikipedia.org/wiki/ADX_(file_format)), in pairs of ``.awb`` and ``.acb`` files. These files can be played and converted by the [vgmstream](https://vgmstream.org/) library, specifically the component for [foobar2000](https://www.foobar2000.org/). Typical audio formats cannot be encoded into the ADX2 file format through freeware means, although CRIWARE should be able to encode these files.
## Jacket Files
Jacket files, otherwise known as the images that are associated with the song, are found in the same folder as the chart files in a ``.dds`` (DirectDraw Surface) file format, which can be opened in software such as [GIMP](https://www.gimp.org/). Jacket files are always in a resolution of 300x300.

91
Music.md Normal file
View File

@ -0,0 +1,91 @@
This is a general documentation of the ``Music.xml`` file present in every music folder under the path ``root¥app¥data¥AXXX¥music¥musicXXXX¥Music.xml``.
# Overview
``Music.xml`` is a singular file that is in the same folder as the charts for a specific song. This file is essentially the metadata of the song, and provides the game with nearly all information about the song excluding the chart itself. Note that this documentation will not include the structure of the entire XML file, only the meanings of it. To create your own ``Music.xml`` file, use a preexisting one as a template, then use the specifications listed here.
The ``Music.xml`` files in this game make frequent use of a stock array layout, shown below:
```xml
<id></id>
<str></str>
<data />
```
Any references to a "stock array" will mean that there is this array format within the value, with the ``<id>`` and ``<str>`` tags having their values specified. ``<data />`` will never contain any values, and will always be formatted as such.
# Tags
## dataName
The ``<dataname>`` tag will have a single value named after the parent folder, usually ``musicXXXX``.
## formatVersion
The ``<formatVersion>`` tag will always have a value of ``10000``.
## resourceVersion
The ``<resourceVersion>`` tag always contains a stock array with an ``<id>`` value of ``0`` and a ``<str>`` value of ``10000``.
## netOpenName
The ``<netOpenName>`` tag contains a stock array with unknown values. A possible explanation is that these values signify the update that the song was originally added to the game from.
## disableFlag
The ``<disableFlag>`` tag has a value of either ``false`` or ``true``. Enabling the disableFlag will make it so that the song does not appear on the song selection screen.
## exType
The ``<exType>`` tag has a value of an integer between 0 and 2. With a value of ``0``, the song becomes a normal song that can be selected from the song selection screen. With a value of ``1``, the song becomes a tutorial song. With a value of ``2``, the song becomes a WORLD'S END song.
## name
The ``<name>`` tag contains a stock array with an ``<id>`` value equal to the last 4 digits of the parent folder's name, removing any preceeding 0s, and a ``<str>`` value containing the name of the song as it will appear in-game.
## rightsInfoName
The ``<rightsInfoName>`` tag contains a stock array with an ``<id>`` value equal to the corresponding ``rightsInfo`` file in the ``root¥app¥data¥AXXX¥rightsInfo¥rightsInfoXXXXXX`` folder, removing any preceeding 0s, and a ``<str>`` value containing the name of the rights holder as it appears in the ``RightsInfo.xml`` file's ``name`` tag (not how it appears in-game). If the song does not need a rights disclaimer, then the ``<id>`` has a value of ``-1`` and the ``<str>`` has a value of ``Invalid``.
## sortName
The ``<sortName>`` tag contains the name of the song in a format that can be sorted alphabetically. All Latin characters become capitalized, and all punctuation and spaces are removed. For titles in Japanese, all hiragana and kanji are converted into their katakana counterpart.
## artistName
The ``<artistName>`` tag contains a stock array with an ``<id>`` value equal to the ID of the artist, and a ``<str>`` value of the name of the artist as it will appear in-game. If the artist was not previously used in a song, it should be given the same ID as the song. If an artist was previously used, it should be given the same ID as the artist ID used in those previous songs.
## genreName
The ``<genreName>`` tag contains a ``<list>`` tag, which contains a ``<StringID>`` tag, which contains a stock array, with an ``<id>`` value equal to the ID of the genre in question according to the ``GenreSort.xml`` file found in ``root¥app¥data¥AXXX¥music``, and a ``<str>`` value equal to the name of the genre as it appears in the ``GenreSort.xml`` file.
## worksName
The ``<worksName>`` tag contains a stock array, with an ``<id>`` value equal to the ID of the work that the song originates from, and a ``<str>`` value equal to the name of the work in question. This follows the same specifications as ``<artistName>``. If the song does not need a rights disclaimer, then the ``<id>`` has a value of ``-1`` and the ``<str>`` has a value of ``Invalid``.
## jaketFile
The ``<jaketFile>`` tag contains a ``<path>`` tag, with a value equal to the name of the file that contains the jacket of the song, usually found in the same directory as the Music.xml file.
## firstLock
The ``<firstLock>`` tag has a value of either ``false`` or ``true``. If the value is ``true``, then the song will not be listed on the song selection screen unless specific criteria has been fulfilled to unlock the song.
## priority
The ``<priority>`` tag always has a value of ``0``. With a value of ``1``, there does not appear to be any difference.
## cueFileName
The ``<cueFileName>`` tag contains a stock array with an ``<id>`` value equal to the ID of the cueFile as seen in the ``CueFile.xml`` file found in ``root¥app¥data¥AXXX¥cueFile¥cueFileXXXXXX``.
## previewStartTime
The ``<previewStartTime>`` tag contains an integer that designates the location in the song, in milliseconds, that the preview, the part of the song that plays when the song is highlighted on the song selection screen, will start.
## previewEndTime
The ``<previewEndTime>`` tag contains an integer that designates the location in the song, in milliseconds, that the preview will end. After ending, it will loop back to the ``<previewStartTime>``.
Todo: worldsEndTagName, starDifType, stageName, and fumens array.

328
README.md
View File

@ -1,325 +1,9 @@
This is an informative document on how the charts in Chunithm are formatted and function. This is **not** meant to be a complete guide on how to create custom charts for Chunithm. All information on this document was discovered via personal research. Contributions and further research are welcome. This document may be used for any purpose, including the creation of a tool to create Chunithm charts. See [UNLICENSE](https://github.com/Suprnova123/Chunithm-Charting-Research/blob/main/UNLICENSE) for more information. This is an informative document on how the files in Chunithm are formatted and function. This is **not** meant to be a complete guide on how to create custom charts for Chunithm. All information on this document was discovered via personal research. Contributions and further research are welcome. This document may be used for any purpose, including the creation of a tool to create Chunithm charts. See [UNLICENSE](https://github.com/Suprnova123/Chunithm-Charting-Research/blob/main/UNLICENSE) for more information. For disclaimers and copyright attributions, please see [DISCLAIMER](https://github.com/Suprnova123/Chunithm-Charting-Research/blob/main/DISCLAIMER).
# Things to know # Contents
* Most counting in this file format starts from 0. A measure of 0 means at the beginning of the song, a cell of 0 means the first cell on the left, etc. * [General Information](https://github.com/Suprnova123/Chunithm-Charting-Research/blob/main/General.md)
* The location for song files on most versions of the game can be found in ``Chunithm¥app¥data¥¥AXXX¥music¥musicXXXX``. The file format for charts is ``.c2s``, and are plain text files that can be opened in tools like Notepad++. * [Charting](https://github.com/Suprnova123/Chunithm-Charting-Research/blob/main/Charting.md)
* A cell is the corresponding key for the note on the playfield. The playfield has 16 columns, numbers from 0-15 from left to right. * [Music](https://github.com/Suprnova123/Chunithm-Charting-Research/blob/main/Music.md)
* A measure is a function of time containing a specific amount of beats. Each measure usually contains 4 beats, and stays relatively consistent throughout the song.
# Tags (More documents are to come)
## **BPM**
Designates the BPM for the specified measure of the song.
### Schema:
| Beginning Measure | Offset | BPM |
| ---- | ---- | ---- |
## **MET**
Designates the time signature for the specified measure of the song.
### Schema:
| Beginning Measure | Offset | Second Value | First Value |
| ---- | ---- | ---- | ---- |
It is very important to note that the values for the time signature are in reverse. It is also worth mentioning that this is purely cosmetic. The only thing that this value will affect is the placement of the thin measure lines on the playfield.
## **SFL**
Designates the speed of the playfield at the specified measure of the song.
### Schema:
| Beginning Measure | Offset | Duration | Multiplier |
| ---- | ---- | ---- | ---- |
It is important to note that the multiplier must have an accuracy of 0.000001, meaning that it should have six digits after the decimal point. This value will multiply the player's current playfield speed, so notes will appear faster or slower based on this value. This value is purely cosmetic, and will not affect the placement of notes in the .c2s file, only the player will see a difference. This value can also be made negative, which will result in the board moving in reverse, usually used for aesthetic purposes such as [this section of Fracture Ray's MASTER chart](https://youtu.be/5m7bMyIDoec?t=48).
# Notes
## Universal Note Schema
| Note Type | Measure | Offset | Cell | Width |
| ---- | ---- | ---- | ---- | ---- |
### **Note Type**
A note type is the type of note that you want to be placed at this particular point. There are various types of notes that can be used, and most of them will have additional variables that will be appended to the end of the typical schema. There will be more information later on explaining each of these notes.
#### **Note Types:**
* TAP (tap)
* CHR (ex-note)
* HLD (hold)
* SLD (slide)
* SLC (slide control point)
* FLK (flick)
* AIR (air)
* AUR (air up-right)
* AUL (air up-left)
* AHD (air hold)
* ADW (air downwards)
* ADR (air down-right)
* ADL (air down-left)
* MNE (mine)
### **Measure**
The measure is the specific measure that you want the note to be placed in. Each measure is (usually) 4 beats. The value starts from 0 and continues infinitely, although should always end with the song.
### **Offset**
A function of time to show how offset a note or timing point should be from the measure. This relies on the resolution of the song, designated by the RESOLUTION tag. The full resolution is an entire measure, so with a resolution of 384, the first beat of a measure would be 0, the second would be 96, the third would be 192, the fourth would be 288. To get the desired beat, divide the resolution by 4, multiply it by the beat that you want, and then subtract it by the resolution divided by 4.
For a fraction of a beat, divide the resolution by 4, then multiply it by the fraction of the beat you want. Then add that result with the desired beat.
The function for this would be:
```b(r/4)-(r/4) + f(r/4)```
where b is the desired beat rounded down to a whole number, r is the resolution of the song, and f is the fraction of the beat.
For example, if I wanted a note on the 2 1/2th beat of a 4 beat song with a resolution of 384, I would perform the following:
```
2(384/4)-(384/4) + 1/2(384/4)
192 - 96 + 48
144
```
### **Cell**
As stated above, the cell is the numerical ID for the column in the playfield that the note should appear in. Note that this value should be the column that the note first appears in **from the left**.
### **Width**
Separate from the Cell value, the Width value notes how wide the note should be, extending from the value listed in Cell to the right. The minimum value is 1, which means that the note only occupies the column listed in cell. As an example, a width of 3 on a note with a cell value of 7 would have the note occupy columns 7, 8, and 9.
## Additional Note Values
Most note types require additional information to function correctly. This section will provide an example of the schema that the note uses, followed by an explanation for any values not included in the universal schema. Any values in quotes indicate a value that is consistent with that note.
### **Tap**
Tap notes are the most basic notes that can be charted. They simply require the player to hit the cell that the note occupies at the required time.
#### Schema:
| "TAP" | Measure | Offset | Cell | Width |
| ---- | ---- | ---- | ---- | ---- |
Tap notes do not differ from the universal schema listed above.
### **Ex-Notes**
Ex-Notes are similar to tap notes, although they give the player more score for hitting them accurately.
#### Schema:
| "CHR" | Measure | Offset | Cell | Width | Unknown |
| ---- | ---- | ---- | ---- | ---- | ---- |
* Unknown: Seems to always have a value of "UP" or "CE".
### **Hold**
Hold notes are similar to tap notes, but require the player to keep the designated cell pressed over a continuous period of time.
#### Schema:
| "CHR" | Measure | Offset | Cell | Width | Duration |
| ---- | ---- | ---- | ---- | ---- | ---- |
* Duration: The amount of time that the note needs to be held down for. This value is based on the same format for offset.
### **Slide**
Slide notes are similar to hold notes, but are capable of moving between cells while sustaining the hold. There are two types of slide notes, SLD and SLC. Slides that start with a straight line begin with an SLD, while slides that start immediately with movement start with an SLC. All slides end with an SLD note.
#### Schema:
| "SLD"/"SLC" | Measure | Offset | Cell | Width | Duration | End Cell | End Width |
| ---- | ---- | ---- | ---- | ---- | ---- | ---- | ---- |
* Duration: The amount of time that the note will take to move to the target cell. This value is based on the same format for offset.
* End Cell: The column that the slide will move towards over the duration of the slide. Similar to the Cell value, this value will be where the left side of the cell is, and can be anywhere from 0-15. To have a slide that stays straight over the duration, make the End Cell value the same as the Cell value.
* End Width: The width that the slide will have at the end of the duration. Similar to the Width value, this value can be anywhere between 1-16. If the End Width differs from the original Width, the slider will gradually shrink or expand in width over the course of the slide.
A slide will not end until you call an SLD in the same cell that another slide is in at that moment in time. To adjust a slide without interrupting it, use SLC.
The feature of sliders shaking from side to side rapidly is not a built-in function of the game, it instead simply involves having the slider move left and right a few cells on very short offsets.
### **Flick**
A flick note involves the player having their finger within the cells that the flick inhabits, and then swiping to the left or the right depending on which direction the flick has.
#### Schema:
| "FLK" | Measure | Offset | Cell | Width | Direction |
| ---- | ---- | ---- | ---- | ---- | ---- |
* Direction: The direction that the user is meant to swipe in. The possible values are "L" for left and "R" for right.
### **Air**
An air note involves the player raising their hands through the IR sensors above the physical keyboard. Unlike other notes, these notes act as modifiers for already existing notes. There are also different cosmetic versions of the note, however they each function identically.
#### Schema:
| "AIR"/"AUR"/"AUL" | Measure | Offset | Cell | Width | Target Note |
| ---- | ---- | ---- | ---- | ---- | ---- |
* AIR/AUR/AUL: Each of these note types are identical functionality-wise, although affect the appearance of the arrow above the note. AIR has an upwards arrow, AUR has an up-right arrow, and AUL has an up-left arrow.
* Target Note: This value designated what note the Air note "leeches" off of. You should have this note be in the same cell, measure, and offset as the Air note. It's also recommended to only use this note at the end of a note, rather than in the middle of a sustained note. This recommendation can be discarded for high-level charts.
## **Air Hold**
An air hold note involves having the player hold their hands up towards the sensor after performing an air note. Air holds will always end with a mid-air downwards note automatically.
#### Schema:
| "AHD" | Measure | Offset | Cell | Width | Target Note | Duration |
| ---- | ---- | ---- | ---- | ---- | ---- | ---- |
* Target Note: This value designated what note the Air note "leeches" off of. You should have this note be in the same cell, measure, and offset as the Air note. It's also recommended to only use this note at the end of a note, rather than in the middle of a sustained note. This recommendation can be discarded for high-level charts.
* Duration: The amount of time that the note will take to move to the target cell. This value is based on the same format for offset.
To have mid-air downwards notes in a sustained air note, make the first air hold note last until the point where the mid-air note would be, then add another air hold note that starts at the same offset where the preceeding air hold note ends.
### **Downwards**
A downwards note involves the player lowering their hands through the IR sensors above the physical keyboard. Unlike other notes, these notes act as modifiers for already existing notes. There are also different cosmetic versions of the note, however they each function identically.
#### Schema:
| "ADW"/"ADR"/"ADL" | Measure | Offset | Cell | Width | Target Note |
| ---- | ---- | ---- | ---- | ---- | ---- |
* ADW/ADR/ADL: Each of these note types are identical functionality-wise, although affect the appearance of the arrow above the note. ADW has a downwards arrow, ADR has a down-right arrow, and ADL has a down-left arrow.
* Target Note: This value designated what note the downwards note "leeches" off of. You should have this note be in the same cell, measure, and offset as the downwards note. It's also recommended to only use this note at the end of a note, rather than in the middle of a sustained note. This recommendation can be discarded for high-level charts.
### **Mines**
A mine note involves the player not touching the cell that the mine is placed on. Touching the cell will result in the player losing score and possibly failing the track.
| "MNE" | Measure | Offset | Cell | Width |
| ---- | ---- | ---- | ---- | ---- |
Mine notes require the same information as Tap notes, and simply follow the universal schema mentioned above.
# Demonstration
Below is an excerpt from the .c2s file for Cyaegha's MASTER difficulty, which has a RESOLUTION of 386.
```
TAP 8 0 6 4
TAP 8 0 12 4
SLC 8 96 4 4 7 3 4
TAP 8 96 10 4
SLC 8 103 3 4 10 2 4
SLC 8 113 2 4 13 1 4
SLC 8 126 1 4 22 0 4
SLD 8 148 0 4 236 0 4
TAP 8 192 8 4
SLC 8 288 6 4 4 7 4
SLC 8 292 7 4 12 9 4
SLC 8 304 9 4 9 10 4
SLC 8 313 10 4 12 11 4
SLC 8 325 11 4 23 12 4
SLD 8 348 12 4 36 12 4
AHD 9 0 0 4 SLD 192
CHR 9 0 4 8 CE
AIR 9 0 4 8 CHR
AHD 9 0 12 4 SLD 192
TAP 9 288 3 4
TAP 9 288 9 4
```
Below is what the gameplay for this section looks like. This will be broken down into each line of the .c2s file to see their corresponding patterns in gameplay.
![Demonstration of Cyaegha Excerpt](https://raw.githubusercontent.com/Suprnova123/Chunithm-Charting-Research/main/_assets/cyaegha%20example.gif)
The two tap notes at the beginning appear as:
```
TAP 8 0 6 4
TAP 8 0 12 4
```
The order of values in these lines is the following:
``Tap note | on the 8th measure | with an offset of 0 | starts on cell 6/cell 12 | extends 4 cells to the right``
You can tell that these notes are supposed to occur at the same time because the share the same measure and offset. Remember that the cells are labelled as 0-15, meaning that the first cell on the left is cell 0.
The next two notes are a slide and a tap that occur at the same time. These appear in the document as:
```
SLC 8 96 4 4 7 3 4
TAP 8 96 10 4
```
Note that the slide has the note type of SLC, since the slider starts in motion. If the slider was stationary at the beginning, it would've had an SLD note type.
The order of values for the slide note is the following:
``Slide note | on the 8th measure | with an offset of 96 | starts on cell 4 | extends 4 cells to the right | has a duration of 7 resolution | ends on cell 3 | ends with a width of 4``
There are a few important things to note here. For one, with a measure of 8 and an offset of 96, this means that the note happens on the second beat of the 8th measure (remember, an offset of 0 means the first beat). It also has a very short duration, at only 7 resolution. This means that the slider only lasts for almost 2/100th of a measure. The reason it's so short is because it's designed to look like a curve. There are later SLC notes that attach to the first slider that gradually change to the shape to a curve.
The tap note later on has an order of values of:
``Tap note | on the 8th measure | with an offset of 96 | starts on cell 10 | extends 4 cells to the right``
Again, since the two notes occur at the same measure and offset, they are simultaneous.
The next notes are several control points for a slider, as well as creating a new slider, and a tap note. Their lines are:
```
SLC 8 103 3 4 10 2 4
SLC 8 113 2 4 13 1 4
SLC 8 126 1 4 22 0 4
SLD 8 148 0 4 236 0 4
TAP 8 192 8 4
SLC 8 288 6 4 4 7 4
SLC 8 292 7 4 12 9 4
SLC 8 304 9 4 9 10 4
SLC 8 313 10 4 12 11 4
SLC 8 325 11 4 23 12 4
SLD 8 348 12 4 36 12 4
```
There are several important things to note here. For one, the SLCs at the top are within very quick succession of each other. As stated above, this is because it's creating a curved slider, so it's very precise to look smooth. There is also an SLD immediately after it, which has a duration of 236 resolution. This is important because you can see that this slider is supposed to end at the same time as the other slider. If you add together the offset, which is 148, and the duration, you'll get a value of 384. If you add together the offset and duration of the second SLD at the bottom, you also get 384. Since they are both on the same measure, this shows that they will end at the same time as each other. It's also worth mentioning that the second pair of SLCs are not related to the first pair. They start on a separate cell from the other slider, so it creates a new slider instead of extending a previous one.
The final part of the excerpt contains several air notes, an air hold, an ex-note, and several tap notes. These appear in the file as:
```
AHD 9 0 0 4 SLD 192
CHR 9 0 4 8 CE
AIR 9 0 4 8 CHR
AHD 9 0 12 4 SLD 192
TAP 9 288 3 4
TAP 9 288 9 4
```
You'll notice that both AHDs, the AIR, and the CHR notes all start at the same time, since they share the same measure and offset. Let's break down each note.
The AHD notes represents the following:
``Air hold note | on the 9th measure | with an offset of 0 | starts on the 0th cell/12th cell | extends to the right by 4 cells | leaches off of the Slider note that occupies that same cell | has a duration of 192 resolution``
The CHR note represents:
``Ex-note | on the 9th measure | with an offset of 0 | starts on the 4th cell | extends to the right by 8 cells | CE modifier``
The AIR note represents:
``Air note | on the 9th measure | with an offset of 0 | starts on the 4th cell | extends to the right by 8 cells | leaches off of the ex-note that occupies the same cell``
The excerpt finally ends with two TAP notes, which mean the following:
``Tap note | on the 9th measure | with an offset of 288 | starts on the 3rd/9th cell | extends to the right by 4 cells``
This concludes the analysis of this excerpt of Cyaegha.
# Disclaimer
This document does not condone the illegal piracy, operation, modification, or reverse engineering of Chunithm arcade games, nor any games licensed by Sega, as such actions may violate Japanese and international law.