PhiZone Player

PhiZone Player is an HTML5 Phigros chart player/simulator based on Phaser.

Frameworks

This project is made possible by:

• Phaser
• Svelte
• Vite
• TypeScript

Introduction

Much of this program resembles any other Phigros chart player/simulator, so this section will focus solely on its unique features.

User-friendly landing page

Designed with Preline UI and daisyUI, the landing page is meticulously written to be as intuitive yet powerful as possible.

Choose either some files (or .zip/.pez archives) or an entire folder, and chart bundles will be automatically detected according to Re: PhiEdit (or RPE) metadata files (typically named info.txt) in which a chart, a song, and an illustration are specified. Any other files that fail to be recognized, which are most likely multimedia that will be referenced by the chart, or the extra.json from Phira, will be presented in the assets.

On desktop platforms, you can open .zip/.pez archives directly with the PhiZone Player app.

On mobile platforms, you can share chart archives to the app so that it can receive and resolve them.

Additionally, the program can automatically download files from URLs specified in the zip and file search parameters. A zip parameter should be provided a URL to a zip archive, while a file parameter should be provided a URL to a regular file.

Innovative keyboard controls

Similar to a video player, the program includes handy keyboard controls that are available in autoplay/practice mode:

• Pause/Resume: Press Space to toggle. (In practice mode, press ⇧ Shift+Space to pause.)
• Rewind/Forward: Use ← / → to jump 5 seconds, or ⇧ Shift+← / ⇧ Shift+→ for precise 0.1-second adjustments.

Besides, ESC is always available to pause with/resume from the pause screen, and you can use alphanumeric and punctuation keys on your keyboard to hit the notes when autoplay is off.

APNG support

Animated PNGs are an excellent alternative to GIFs, offering enhanced color fidelity and the support of an 8-bit alpha channel for smoother transparency effects.

An APNG acts exactly the same way as a GIF does, unless the number of repetitions is specified in the file, according to the APNG specification.

Z indexes

The Z index (depth) defines the order in which game objects are rendered. The lower the value, the earlier they are rendered.

Default Z index (depth)	Object(s)
0	Illustration
1	Background video, if present
[2, 3)	Judgment lines, the order of which are determined by their zOrder values
3	Hold notes
4	Drag notes
5	Tap notes
6	Flick notes
7	Hit effects
8	Pause button
9	Combo counter
10	Text beneath the combo counter
11	Score
12	Std deviation & accuracy
13	Progress bar
14	Song title
15	Level name & difficulty

The Z indexes of judgment lines whose zIndex is not present (see Chart enhancements) are calculated based on their zOrder values (code here). Simply put, the values are mapped onto [0, 1) and made equally spaced, and then get added by 2 to become Z indexes. See examples below.

zOrder	Z index
0, 10, 20, 30	2, 2.25, 2.5, 2.75
127, 0, 0, 1	2.6667, 2, 2, 2.3333
1, 2, 5, 6, 114514	2, 2.2, 2.4, 2.6, 2.8

Chart enhancements

Aside from adding support of RPE features, we've also designed some original properties for judgment lines & notes.

Property	Value(s)	Example	Description
scaleOnNotes	0: none; 1: scale; 2: clip	"scaleOnNotes": 2	Belongs to a judgment line. Decides how scaleX events affect notes. Defaults to 0.
appearanceOnAttach	0: hidden; 1: white colored; 2: FC/AP colored	"appearanceOnAttach": 2	Belongs to a judgment line. Decides how the line will be displayed when a UI component or any video is attached to it. Color events will override the color defined by these options. Defaults to 0.
integrateSpeedEasings	false: treat non-linear speed easings directly as height over time; true: integrate speed easings to obtain height functions	"integrateSpeedEasings": true	Belongs to a judgment line. Decides how the easing functions of all speed events of the line will be interpreted. Defaults to false for pre-1.7 charts and true for charts on 1.7 and later versions.
zIndex	an integer or a float	"zIndex": 3.5	Belongs to a judgment line or note. Sets the Z index for the object. For a judgment line, this property, if set, overrides the zOrder property, allowing for more control over on which layer the line should be displayed. For default values, see Z indexes.
zIndexHitEffects	an integer or a float	"zIndexHitEffects": 6.5	Belongs to a note. Sets the Z index for the hit effects of the note. Defaults to 7.
tint	[R, G, B], as seen in colorEvents; null	"tint": [255, 0, 0]	Belongs to a note. Sets the tint for the note. Defaults to null.
tintHitEffects	[R, G, B], as seen in colorEvents; null	"tintHitEffects": [255, 0, 0]	Belongs to a note. Sets the tint for the hit effects of the note. Defaults to null.
judgeSize	a positive number or 0	"judgeSize": 1.5	Belongs to a note. Determines the width of the judgment area of the note. Defaults to size.

Video enhancements

Support of videos in extra.json gets extended with the following new properties for each entry in the videos list:

Property	Type	Description
zIndex	Number	Determines the Z index for this video. Defaults to 1.
attach	Object	Attaches this video to a judgment line, if this property is present. See below for details.

Properties residing in the attach object:

Property	Type	Description
line	Number	Determines which line this video is attached to.
positionXFactor (optional)	Number	Multiplied by the x position of the line, determines the x position of this video. Defaults to 1.
positionYFactor (optional)	Number	Multiplied by the y position of the line, determines the y position of this video. Defaults to 1.
rotationFactor (optional)	Number	Multiplied by the rotation of the line, determines the rotation of this video. Defaults to 1.
alphaFactor (optional)	Number	Multiplied by the alpha of the line, determines the alpha of this video, together with the alpha property of the video itself. Defaults to 1.
tintFactor (optional)	Number	Multiplied by the tint of the line, determines the tint of this video. Defaults to 1.
scaleXMode (optional)	Number	Determines how scaleX events of the line affect this video. Values same as in scaleOnNotes. Defaults to 0.
scaleYMode (optional)	Number	Determines how scaleY events of the line affect this video. Values same as in scaleOnNotes. Defaults to 0.

Shader enhancements

Except for WebGL's incompatibilities with newer versions of GLSL, the program supports not only all the shader features defined by extra.json, but also one original addition to the standard: target range.

A target range defines a list of depth-adjacent (next to each other on the Z axis) game objects that a shader event is applied to. It belongs directly to a shader event (as the optional targetRange property) and consists of the following properties:

Property	Type	Description
minZIndex	Number	Defines the minimum Z index (depth) of this range. Inclusive.
maxZIndex	Number	Defines the maximum Z index (depth) of this range. Exclusive.