Class HitCircle

Graphical representation of a Hit Circle, displayed on the Beatmap Canvas by the HitObjectManager, and checked for mouse click by the BeatmapRunner.

Inheritance

Object

Object

Component

Behaviour

MonoBehaviour

HitCircle

Implements

IHitObjectWithEvents

IHitObject

Namespace: MouseDance.Runtime

Assembly: MouseDance.Runtime.dll

Syntax

public class HitCircle : MonoBehaviour, IHitObjectWithEvents, IHitObject

Remarks

The Hit Circle takes care of its own animations, such as fading in and out, doing the "shrinking" animation for the Approach Circle, doing a shake animation when player pressed it out of sequence. Hit and miss visual effects on the other hand, are handled by the HitObjectManager.

Fields

_approachCircle

Declaration

[Header("Approach Circle")]
[SerializeField]
[Tooltip("Used to animate the Approach Circle's size.")]
protected RectTransform _approachCircle

Field Value

Type	Description
RectTransform

_approachCircleFinalSize

Diameter of the Approach Circle at the end of its animation. This is usually the same value as the _hitCircleSize.

Declaration

protected float _approachCircleFinalSize

Field Value

Type	Description
Single

_approachCircleFinalSizeMultiplier

Declaration

[SerializeField]
[Tooltip("How big the Approach Circle should be at its final position, relative to the Start Cap's size. Default is 1 (same size as the Start Cap size). If your Start Cap has a custom shape and the Approach Circle is still visible at its final position, you may want to set this to a value smaller than 1.")]
protected float _approachCircleFinalSizeMultiplier

Field Value

Type	Description
Single

_approachCircleImage

Declaration

[SerializeField]
[Tooltip("Used to fade-in or fade-out the Approach Circle as needed.")]
protected Image _approachCircleImage

Field Value

Type	Description
UnityEngine.UI.Image

_approachCircleOpacity

Declaration

[SerializeField]
[Tooltip("Final opacity of the Approach Circle once it's fully faded-in. Normally set to 1.0, but you can set this to less than 1.0 if you want the Approach Circle to be transparent even after it has faded-in.")]
[Range(0F, 1F)]
protected float _approachCircleOpacity

Field Value

Type	Description
Single

_approachCircleStartSize

Diameter of the Approach Circle at the start. This is naturally larger than the final size, since the Approach Circle shrinks as time goes by.

Declaration

protected float _approachCircleStartSize

Field Value

Type	Description
Single

_beatmapRunner

Needed to report to the game when user pressed the Hit Circle.

Declaration

protected IBeatmapRunner _beatmapRunner

Field Value

Type	Description
IBeatmapRunner

_borderScaleAtSmallestCircleSize

Declaration

[SerializeField]
[Tooltip("What the Border Image's scale needs to be when this Hit Circle is set to Circle Size 10. Leave at 1.0 if adjustment is not necessary.")]
protected float _borderScaleAtSmallestCircleSize

Field Value

Type	Description
Single

_colliderSizeOffset

Declaration

[SerializeField]
[Tooltip("Adjustment to the size of the Collider after it is resized according to the Circle Size. This value is added (or subtracted if this value is negative). Leave at 0 if not needed.")]
protected float _colliderSizeOffset

Field Value

Type	Description
Single

_doShake

Whether to do a shake animation right now or not.

Declaration

protected bool _doShake

Field Value

Type	Description
Boolean

_fadeOutDueToPressed

True: If Hit Circle is currently being faded-out, then the reason for it fading out is because it was pressed.
False: If Hit Circle is currently being faded-out, then the reason for it fading out is because lifetime was over and it was not pressed.

Declaration

protected bool _fadeOutDueToPressed

Field Value

Type	Description
Boolean

_growHitCircleOnShow

Declaration

[SerializeField]
[Tooltip("Do we animate the Hit Circle growing in size at the same time that it's being faded-in?")]
protected bool _growHitCircleOnShow

Field Value

Type	Description
Boolean

_hitCircle

Declaration

[Header("Hit Circle")]
[SerializeField]
[Tooltip("Used to properly set the size of the Hit Circle.")]
protected RectTransform _hitCircle

Field Value

Type	Description
RectTransform

_hitCircleBorder

Declaration

[SerializeField]
protected Image _hitCircleBorder

Field Value

Type	Description
UnityEngine.UI.Image

_hitCircleImage

Declaration

[SerializeField]
[Tooltip("Used to fade the Hit Circle in and out as needed.")]
protected Image _hitCircleImage

Field Value

Type	Description
UnityEngine.UI.Image

_hitCircleRadiusMultiplier

Declaration

[Header("Settings")]
[SerializeField]
[Tooltip("Multiplier to the Hit Circle size. 1.0 means no change. Greater than 1 means bigger, lesser than 1 means smaller. This multiplier is applied on top of the Osu file's \"Circle Size\" setting, and even on top of the MouseDance.Runtime.HitObjectManager's Circle Radius Multiplier.")]
protected float _hitCircleRadiusMultiplier

Field Value

Type	Description
Single

_hitCircleSize

Diameter of the Hit Circle.

Declaration

protected float _hitCircleSize

Field Value

Type	Description
Single

_manager

Needed to allow this Hit Circle to be despawned and moved back to pool for reusing, and for reporting when user has pressed the Hit Circle right or wrong so it can play the proper sound/visual fx.

Declaration

protected HitObjectManager _manager

Field Value

Type	Description
HitObjectManager

_originalPosition

We keep track of the position this Hit Circle is initially shown in, so that we can return to it after doing a shake animation.

Declaration

protected Vector2 _originalPosition

Field Value

Type	Description
Vector2

_positionOffset

Declaration

[SerializeField]
[Tooltip("If the game is shown or positioned in some special way, you can add an offset to the positions of Hit Circles here. Leave value at (0, 0) if not needed.")]
protected Vector2 _positionOffset

Field Value

Type	Description
Vector2

_rectTransform

Declaration

[SerializeField]
[Tooltip("Used for positioning the Hit Circle.")]
protected RectTransform _rectTransform

Field Value

Type	Description
RectTransform

_shakeEndTime

Absolute time when to end shaking animation.

Declaration

protected float _shakeEndTime

Field Value

Type	Description
Single

_startBorderScaleAfter

Declaration

[SerializeField]
[Tooltip("Start scaling the Border Image towards \"Border Scale At Smallest Circle Size\" after this Circle Size value. So a value of 5 here means, Border Image scale starts getting adjusted when the Circle Size this Hit Circle is set to is 6 to 10.")]
protected int _startBorderScaleAfter

Field Value

Type	Description
Int32

_text

Declaration

[SerializeField]
[Tooltip("Used to display the number on the Hit Circle.")]
protected TextMeshProUGUI _text

Field Value

Type	Description
TMPro.TextMeshProUGUI

_timeStarted

Absolute time the Hit Circle started showing up. This is used to properly calculate the percentage progress of its lifetime.

Declaration

protected float _timeStarted

Field Value

Type	Description
Single

_timeToApproachCircleEnd

Absolute time the Approach Circle will finish.

Declaration

protected float _timeToApproachCircleEnd

Field Value

Type	Description
Single

_timeToApproachCircleFullOpacity

Absolute time when the Approach Circle has completely faded-in.

Declaration

protected float _timeToApproachCircleFullOpacity

Field Value

Type	Description
Single

_timeToApproachCircleStart

Time when Approach Circle should start doing its animation. This is normally same as _timeStarted but can be later, in case Hit Circle was shown even way earlier than the usual preempt duration.

Declaration

protected float _timeToApproachCircleStart

Field Value

Type	Description
Single

_timeToDie

Absolute time the Hit Circle should start fading out.

Declaration

protected float _timeToDie

Field Value

Type	Description
Single

_timeToFadeOutFromPressed

Absolute time when Hit Circle should be at 100% faded-out.

Declaration

protected float _timeToFadeOutFromPressed

Field Value

Type	Description
Single

_timeToHitCircleOpacityFull

Absolute time when Opacity will finally be 100%. This is also the time that the Hit Circle is supposed to be pressed.

Declaration

protected float _timeToHitCircleOpacityFull

Field Value

Type	Description
Single

_timeToHitCircleOpacityPartial

Absolute time when Hit Circle will finish fading-in at Opacity set to HIT_CIRCLE_PARTIAL_OPACITY. After this point in time, fading will pause.

Declaration

protected float _timeToHitCircleOpacityPartial

Field Value

Type	Description
Single

_timeToHitCircleOpacityWaitEnd

Absolute time when pause for fading-in will finish.

Declaration

protected float _timeToHitCircleOpacityWaitEnd

Field Value

Type	Description
Single

APPROACH_CIRCLE_FADE_IN_MULTIPLIER

How long the approach circle fades in. This value isn't the actual duration, but a multiplier on the Approach Rate Duration. Meaning a value of 1.0 means to use the Approach Rate Duration (0.5 would be half, 2.0 would be double, etc). This value is just guessed, based on playing Osu!.

Declaration

public const float APPROACH_CIRCLE_FADE_IN_MULTIPLIER = 0.4F

Field Value

Type	Description
Single

APPROACH_CIRCLE_RADIUS_MULTIPLIER

How bigger than the hit circle the approach circle starts at. This value isn't the actual radius, but a multiplier on the hit circle's radius (2 means double the hit circle's radius). This value is just guessed, based on playing Osu!.

Declaration

public const float APPROACH_CIRCLE_RADIUS_MULTIPLIER = 4.2F

Field Value

Type	Description
Single

DIE_OFF_FADE_OUT_DURATION

Once the hit circle's lifetime is over (and player never managed to press/collect it), it fades-out. This is how long to fade it out (in milliseconds). This value is just guessed, based on playing Osu!.

Declaration

public const float DIE_OFF_FADE_OUT_DURATION = 125F

Field Value

Type	Description
Single

HIT_CIRCLE_FADE_IN_PAUSE_DURATION_MULTIPLIER

Before the hit circle goes to full opacity, it pauses halfway for this duration. This value isn't the actual duration, but a multiplier on the Approach Rate Duration. Meaning a value of 1.0 means to use the Approach Rate Duration (0.5 would be half, 2.0 would be double, etc). This value is just guessed, based on playing Osu!.

Declaration

public const float HIT_CIRCLE_FADE_IN_PAUSE_DURATION_MULTIPLIER = 0.5F

Field Value

Type	Description
Single

HIT_CIRCLE_FULL_FADE_IN_DURATION_MULTIPLIER

Before the hit circle goes to full opacity, it pauses halfway, then finally fades-in to full opacity using this duration. This value isn't the actual duration, but a multiplier on the Approach Rate Duration. Meaning a value of 1.0 means to use the Approach Rate Duration (0.5 would be half, 2.0 would be double, etc). This value is just guessed, based on playing Osu!.

Declaration

public const float HIT_CIRCLE_FULL_FADE_IN_DURATION_MULTIPLIER = 0.3F

Field Value

Type	Description
Single

HIT_CIRCLE_PARTIAL_FADE_IN_DURATION_MULTIPLIER

Before the hit circle goes to full opacity, it fades in to this value first, then pauses for a while. This value isn't the actual duration, but a multiplier on the Approach Rate Duration. Meaning a value of 1.0 means to use the Approach Rate Duration (0.5 would be half, 2.0 would be double, etc). This value is just guessed, based on playing Osu!.

Declaration

public const float HIT_CIRCLE_PARTIAL_FADE_IN_DURATION_MULTIPLIER = 0.2F

Field Value

Type	Description
Single

HIT_CIRCLE_PARTIAL_OPACITY

Before the hit circle goes to full opacity, it uses this value, pauses for a short while, and only then fade-in to full opacity. This value is normalized (0.5 means 50%, 1.0 means 100%). This value is just guessed, based on playing Osu!.

Declaration

protected const float HIT_CIRCLE_PARTIAL_OPACITY = 0.5F

Field Value

Type	Description
Single

PRESSED_FADE_OUT_DURATION

When Hit Circle is pressed/collected (whether in the correct time window or not), it's faded-out. This is how long in milliseconds the fade-out animation takes. It's faster than DIE_OFF_FADE_OUT_DURATION.

Declaration

protected const float PRESSED_FADE_OUT_DURATION = 200F

Field Value

Type	Description
Single

ShakeAmount

When doing a shake animation, this is how much to move (amplitude) in the x-axis in either direction.

Declaration

protected const float ShakeAmount = 3F

Field Value

Type	Description
Single

ShakeDuration

When doing a shake animation, this is how long to do it.

Declaration

protected const float ShakeDuration = 300F

Field Value

Type	Description
Single

ShakeSpeed

When doing a shake animation, this is how fast (frequency) to move.

Declaration

protected const float ShakeSpeed = 50F

Field Value

Type	Description
Single

Properties

Colour

Colour that this Hit Circle is in. Used by visual effects so that their colour matches the Hit Circle's colour.

Declaration

public virtual Color Colour { get; }

Property Value

Type	Description
Color

ComboColourIndex

The index of the colour used by this Hit Circle. This can be used to identify or differentiate this Hit Circle from other Hit Objects that are using a different colour.

Declaration

public virtual int ComboColourIndex { get; protected set; }

Property Value

Type	Description
Int32

ComboCounter

The number displayed on this Hit Circle.

Declaration

public virtual int ComboCounter { get; protected set; }

Property Value

Type	Description
Int32

EffectsPos

When this Hit Circle is pressed or missed, this is the position where the visual effects should spawn in.

Declaration

public virtual Vector3 EffectsPos { get; }

Property Value

Type	Description
Vector3	An (x, y, z) position

Remarks

This is an (x, y, z) position, though the z value is 0 and can be ignored. The only reason why this is a Vector3 and not a Vector2 is so that this value can be easily assigned to a Transform's position.

Index

Index position of this Hit Circle in the entire Beatmap. Starts at 0.

Declaration

public virtual int Index { get; protected set; }

Property Value

Type	Description
Int32

IsEnabled

Informs the BeatmapRunner whether it should consider this Hit Circle as hittable or not. Disabled Hit Circles are "despawned" and are back into the pool and therefore should not be used.

Declaration

public virtual bool IsEnabled { get; }

Property Value

Type	Description
Boolean	True: This Hit Circle is "enabled", currently being used and is on-screen. False: This Hit Circle is considered to be "disabled", currently hidden and not in-use (but is ready to be re-used).

PoolId

Which pool of prefabs this Hit Circle prefab will belong to. Important once it's time to despawn this Hit Circle.

Declaration

public virtual string PoolId { get; protected set; }

Property Value

Type	Description
String

Pressed

Whether this Hit Circle has been pressed already.

Declaration

public virtual bool Pressed { get; protected set; }

Property Value

Type	Description
Boolean	True: Hit Circle has already been pressed. False: This Hit Circle is yet to be pressed.

RequiresHold

Does this Hit Object need to be pressed for a long time? For Hit Circles, this always returns false.

Declaration

public virtual bool RequiresHold { get; }

Property Value

Type	Description
Boolean

Methods

DoShakeAnimation(String)

Make the Hit Circle do a shaking animation with the appropriate sound effect.

Declaration

public virtual void DoShakeAnimation(string effectsId = null)

Parameters

Type	Name	Description
String	effectsId	Optional ID of the specific visual/sound effect to play. Leave at null to use defaults.

Hide()

Hide this Hit Circle immediately (no fade out).

Declaration

public virtual void Hide()

IsNameMatch(String)

Is specified name the kind of name assigned to Hit Circles?

Declaration

public static bool IsNameMatch(string name)

Parameters

Type	Name	Description
String	name

Returns

Type	Description
Boolean

OnPressed(Int32)

Called by the BeatmapRunner to notify this Hit Circle that it's been pressed by the player. This makes the Hit Circle react properly (do a shake animation if pressed out-of-sequence, fade-out if pressed correctly, trigger appropriate hit/miss sound/visual fx)

Declaration

public virtual void OnPressed(int idxThatNeedsToBePressed)

Parameters

Type	Name	Description
Int32	idxThatNeedsToBePressed	The current Hit Object index that should be pressed right now. If this doesn't match the Hit Circle's own Index, then the player clicked out-of-sequence.

OnReleased()

Called by the BeatmapRunner to notify this Hit Circle that the player released their press on it.

Declaration

public virtual void OnReleased()

OnWrongPressed(String)

Called by the BeatmapRunner to notify this Hit Circle that it's been pressed by the player, but somehow pressed it wrong (which is determined by a AllowCollect(IHitObject, IReadOnlyList<IHitObject>)).

Declaration

public virtual void OnWrongPressed(string effectsId = null)

Parameters

Type	Name	Description
String	effectsId	Optional ID of the specific visual/sound effect to play. Leave at null to use defaults.

Resize(Single, Single)

Resize this Hit Circle with specified radius.

Declaration

public virtual void Resize(float radius, float radiusMultiplier)

Parameters

Type	Name	Description
Single	radius	Size of Hit Circle in pixel radius.
Single	radiusMultiplier	Multiplier to the radius coming from CircleRadiusMultiplier.

Show(HitObjectManager, BeatmapRunner, String, Int32, Int32, Int32, Gradient, Color32, Boolean, Boolean, HitCircle, Single, Single, Single, Single, Single)

Show this Hit Circle at specified position, colour, and other properties. This overload also initializes the Hit Circle's reference to the HitObjectManager and BeatmapRunner, and is called for newly instantiated Hit Circles.

Declaration

public virtual void Show(HitObjectManager manager, BeatmapRunner beatmapRunner, string poolId, int idx, int comboCounter, int comboColourIdx, Gradient colour, Color32 borderColour, bool applyColourToApproachCircles, bool showNumber, HitCircle hitCircle, float positionScale, float radius, float radiusMultiplier, float approachStartDelay, float approachRateDuration)

Parameters

Type	Name	Description
HitObjectManager	manager	Which HitObjectManager manages this HitCircle. Needed to allow this Hit Circle to be despawned and moved back to pool for reusing, and for reporting when user has pressed the Hit Circle right or wrong so it can play the proper sound/visual fx.
BeatmapRunner	beatmapRunner	Needed to report to the game when user pressed the Hit Circle for keeping score.
String	poolId	Which pool of prefabs this Hit Circle will belong to.
Int32	idx	Numerical position of this Hit Circle in the entire Beatmap.
Int32	comboCounter	The number that should be displayed in this Hit Circle.
Int32	comboColourIdx	The index of the colour used by this Hit Circle. This can be used to identify or differentiate this Hit Object from others using a different colour.
Gradient	colour	Colour that this Hit Circle should be in.
Color32	borderColour	Colour that this Hit Circle's borders should be in.
Boolean	applyColourToApproachCircles	Whether specified colour should also be applied to the Approach Circle. If false, Approach Circle will just be white.
Boolean	showNumber	Whether to show the number on this Hit Circle or not.
OsuParsers.Beatmaps.Objects.HitCircle	hitCircle	More data on this Hit Circle.
Single	positionScale	How far from the center of the screen this Hit Circle should be placed. This is a multiplier so 2.0 will place this twice as far from the center of the screen. Set to 1.0 if you do not want any scaling.
Single	radius	Size of Hit Circle in pixel radius.
Single	radiusMultiplier	Multiplier to the size coming from CircleRadiusMultiplier.
Single	approachStartDelay	How long do we delay the Approach Circle from showing up and doing its shrinking animation. Used when the Hit Circle is shown in advance, even earlier than its preempt duration. Set to 0 if you do not want a delay.
Single	approachRateDuration	How long it will take for the Approach Circle to do its shrinking animation.

Show(String, Int32, Int32, Int32, Gradient, Color32, Boolean, Boolean, HitCircle, Single, Single, Single, Single, Single)

Show this Hit Circle at specified position, colour, and other properties. This is called on reused Hit Circles.

Declaration

public virtual void Show(string poolId, int idx, int comboCounter, int comboColourIdx, Gradient colour, Color32 borderColour, bool applyColourToApproachCircles, bool showNumber, HitCircle hitCircle, float positionScale, float radius, float radiusMultiplier, float approachStartDelay, float approachRateDuration)

Parameters

Type	Name	Description
String	poolId	Which pool of prefabs this Hit Circle will belong to.
Int32	idx	Numerical position of this Hit Circle in the entire Beatmap.
Int32	comboCounter	The number that should be displayed in this Hit Circle.
Int32	comboColourIdx	The index of the colour used by this Hit Object. This can be used to identify or differentiate this Hit Object from others using a different colour.
Gradient	colour	Colour that this Hit Circle should be in.
Color32	borderColour	Colour that this Hit Circle's borders should be in.
Boolean	applyColourToApproachCircles	Whether specified colour should also be applied to the Approach Circle. If false, Approach Circle will just be white.
Boolean	showNumber	Whether to show the number on this Hit Circle or not.
OsuParsers.Beatmaps.Objects.HitCircle	hitCircle	More data on this Hit Circle.
Single	positionScale	How far from the center of the screen this Hit Circle should be placed. This is a multiplier so 2.0 will place this twice as far from the center of the screen. Set to 1.0 if you do not want any scaling.
Single	radius	Size of Hit Circle in pixel radius.
Single	radiusMultiplier	Multiplier to the size coming from CircleRadiusMultiplier.
Single	approachStartDelay	How long do we delay the Approach Circle from showing up and doing its shrinking animation. Used when the Hit Circle is shown in advance, even earlier than its preempt duration. Set to 0 if you do not want a delay.
Single	approachRateDuration	How long it will take for the Approach Circle to do its shrinking animation.

StartShake()

Make this Hit Circle do a shaking animation for ShakeDuration seconds. You can also call StopShake() to stop it prematurely.

Declaration

protected virtual void StartShake()

StopShake()

Stop this Hit Circle from doing the shaking animation if it's doing that.

Declaration

protected virtual void StopShake()

Update()

Update method called by Unity every frame. This is used to update the Hit Circle's animations (Approach Circle shrinking animation, fading in and out, shake animation).

Declaration

protected virtual void Update()

Implements

IHitObjectWithEvents

IHitObject

Extension Methods

Util.SetLayerDeep(Component, LayerMask)

Util.SetLayerDeep(Component, Int32)

Util.SetLayerDeep(Component, LayerMask, Stack<Transform>)