sscharter 0.8.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 77116185ddcbeeeff551d0584bc35b8a10da9f0d7fcbae95a520b95909c355dd
-  data.tar.gz: 5594955220d37210bf710314b379e88d8a23a5a5174291c7d06c91cf25e37dee
+  metadata.gz: 648753f12016bdf6a3da2c7e82fde0fb3baa65b242e31a853f1cc113a30e2638
+  data.tar.gz: a24123b640ae77b7c49a507201c15bb7bd6a4b70fb2114254f61e2a0bbb4f185
 SHA512:
-  metadata.gz: b67bc6805cf36ab1d69c4b85bbe0dce05d0db8b794caa6c8cc0cc8a7f2f28bb5c840688122527f2e2b44190740756020d4308a0ba0ca3bfbec570108cdf0a108
-  data.tar.gz: 6523d03c7b22171f37829136a21e4a378947eed410dd9f22c825046c6ffdb71269392d65f6b6621cb7c43521e994a8b6fc1d11351d9141432898fd12e61e5dc9
+  metadata.gz: 173cbf0d5e9ab511990e03f467e2819a7c8717599b41e13dd675bb986b3c818ded32bb2b8ce47decad3bba984d57e1359ca56f48e5fa8da7b744e88c768b3853
+  data.tar.gz: e504b089535c14742597e026f497b7c03e662fdda16819b4e238f60c11e70523fe7cb361d61e907fb54bf58b6aa33fa6841b67f71ae1531571df8fa215c579bd

data/Gemfile

@@ -3,3 +3,5 @@
 source "https://rubygems.org"
 
 gemspec
+
+gem 'yard', path: 'gems/yard'

data/Gemfile.lock

@@ -0,0 +1 @@
+lock/ruby-4.0.1-bundler-4.0.8-Gemfile.lock

data/Rakefile

@@ -11,8 +11,14 @@ Rake::TestTask.new :test do |t|
 end
 
 YARD::Rake::YardocTask.new do |t|
-	t.files.concat %w[README.md]
-	t.options.concat %w[--title sscharter --output-dir doc --exclude lib/sscharter/cli.rb --readme]
+	t.options.concat %w[
+		--title sscharter
+		--output-dir doc
+		--exclude lib/sscharter/cli.rb
+		--readme README.md
+		--files tutorial/*.md
+		--type-tag yieldself:Yield\ Self
+	]
 end
 
 task default: :test

data/lib/sscharter/chart.rb

@@ -11,24 +11,66 @@ class Sunniesnow::Chart
 	using Sunniesnow::Utils
 
 	# The schema URL for the output JSON.
-	# This will be set as the `$schema` property in the generated JSON.
+	# This will be set as the +$schema+ property in the generated JSON.
 	SCHEMA = 'https://sunniesnow.github.io/schema/chart-1.0.json'
 
 	# The title of the music.
 	# This is one of the metadata of the chart which will be reflected in the generated JSON.
 	# Also, see
-	# {chart file specifications}[https://sunniesnow.github.io/doc/chart.html#title]
+	# {https://sunniesnow.github.io/doc/chart.html#chart-title chart file specifications}
 	# for more info.
+	# @return [String]
 	attr_accessor :title
-	
+
+	# The artist of the music.
+	# This is one of the metadata of the chart which will be reflected in the generated JSON.
+	# Also, see
+	# {https://sunniesnow.github.io/doc/chart.html#chart-artist chart file specifications}
+	# for more info.
+	# @return [String]
 	attr_accessor :artist
+
+	# The author of the chart.
+	# This is one of the metadata of the chart which will be reflected in the generated JSON.
+	# Also, see
+	# {https://sunniesnow.github.io/doc/chart.html#chart-charter chart file specifications}
+	# for more info.
+	# @return [String]
 	attr_accessor :charter
+
+	# The difficulty name of the chart.
+	# This is one of the metadata of the chart which will be reflected in the generated JSON.
+	# Also, see
+	# {https://sunniesnow.github.io/doc/chart.html#chart-difficulty-name chart file specifications}
+	# for more info.
+	# @return [String]
 	attr_accessor :difficulty_name
+
+	# The difficulty color of the chart.
+	# This is one of the metadata of the chart which will be reflected in the generated JSON.
+	# Also, see
+	# {https://sunniesnow.github.io/doc/chart.html#chart-difficulty-color chart file specifications}
+	# for more info.
+	# @return [String]
 	attr_accessor :difficulty_color
+
+	# The difficulty of the chart.
+	# This is one of the metadata of the chart which will be reflected in the generated JSON.
+	# Also, see
+	# {https://sunniesnow.github.io/doc/chart.html#chart-difficulty chart file specifications}
+	# for more info.
+	# @return [String]
 	attr_accessor :difficulty
+
+	# The difficulty superscript of the chart.
+	# This is one of the metadata of the chart which will be reflected in the generated JSON.
+	# Also, see
+	# {https://sunniesnow.github.io/doc/chart.html#chart-difficulty-sup chart file specifications}
+	# for more info.
+	# @return [String]
 	attr_accessor :difficulty_sup
 
-	# An array of Sunniesnow::Event.
+	# @return [Array<Sunniesnow::Event>]
 	attr_reader :events
 
 	# @param [Integer] live_reload_port The port to use for live reload.
@@ -50,10 +92,10 @@ class Sunniesnow::Chart
 		@production = production
 	end
 
-	##
 	# Convert to JSON.
 	# A Sunniesnow chart is always a JSON file in the level file.
 	# This method is used to generate that JSON file.
+	# @return [String]
 	def to_json *args
 		hash = {
 			'$schema': SCHEMA,
@@ -70,13 +112,13 @@ class Sunniesnow::Chart
 			version: Sunniesnow::Charter::VERSION,
 			port: @live_reload_port
 		} unless @production
-		hash.to_json
+		hash.to_json *args
 	end
 end
 
 class Sunniesnow::Event
-	
-	attr_accessor :time, :type
+
+	attr_accessor :time, :type, :time_dependent
 	attr_reader :properties
 
 	def initialize time, type, **properties
@@ -94,6 +136,8 @@ class Sunniesnow::Event
 	end
 
 	def to_json *args
-		{time: @time, type: @type, properties: @properties}.to_json
+		result = {time: @time, type: @type, properties: @properties}
+		result[:timeDependent] = @time_dependent if @time_dependent
+		result.to_json *args
 	end
 end

data/lib/sscharter/charter/basic_events.rb

@@ -0,0 +1,277 @@
+# frozen_string_literal: true
+
+class Sunniesnow::Charter
+
+	# Aliases for some directions that can be used with {#flick}.
+	DIRECTIONS = {
+		right: %i[r],
+		up_right: %i[ur ru],
+		up: %i[u],
+		up_left: %i[ul lu],
+		left: %i[l],
+		down_left: %i[dl ld],
+		down: %i[d],
+		down_right: %i[dr rd]
+	}.each_with_object({
+		right: 0.0,
+		up_right: Math::PI / 4,
+		up: Math::PI / 2,
+		up_left: Math::PI * 3 / 4,
+		left: Math::PI,
+		down_left: -Math::PI * 3 / 4,
+		down: -Math::PI / 2,
+		down_right: -Math::PI / 4
+	}) do |(direction_name, aliases), directions|
+		aliases.each { directions[_1] = directions[direction_name] }
+	end.freeze
+
+	# @!group DSL Methods
+
+	# Creates a tap note at the given coordinates with the given text.
+	# The coordinates +x+ and +y+ must be numbers.
+	# The argument +text+ is the text to be displayed on the note
+	# (it is converted to a string via +to_s+ if it is not a string).
+	#
+	# Technically, this adds an event of type +:tap+ to the chart at the current time
+	# with properties containing the information provided by +x+, +y+, and +text+.
+	# @param x [Numeric] the x-coordinate of the note.
+	# @param y [Numeric] the y-coordinate of the note.
+	# @param text [String] the text to be displayed on the note.
+	# @return [Event] the event representing the tap note.
+	# @raise [ArgumentError] if +x+ or +y+ is not a number.
+	# @example
+	#   offset 0.1; bpm 120
+	#   t 0, 0, 'Hello'
+	#   t 50, 0, 'world'
+	#   # Now there are two simultaneous tap notes at (0, 0) and (50, 0)
+	#   # with texts 'Hello' and 'world' respectively
+	def tap x, y, text = ''
+		if !x.is_a?(Numeric) || !y.is_a?(Numeric)
+			raise ArgumentError, 'x and y must be numbers'
+		end
+		event :tap, x: x.to_f, y: y.to_f, text: text.to_s
+	end
+	alias t tap
+
+	# Creates a hold note at the given coordinates with the given duration and text.
+	# The coordinates +x+ and +y+ must be numbers.
+	# The argument +duration_beats+ is the duration of the hold note in beats.
+	# It needs to be a positive Rational or Integer.
+	# If it is a Float, it will be converted to a Rational, and a warning will be issued.
+	# The argument +text+ is the text to be displayed on the note
+	# (it is converted to a string via +to_s+ if it is not a string).
+	#
+	# Technically, this adds an event of type +:hold+ to the chart at the current time
+	# with properties containing the information provided by +x+, +y+, +duration_beats+, and +text+.
+	# @param x [Numeric] the x-coordinate of the note.
+	# @param y [Numeric] the y-coordinate of the note.
+	# @param duration_beats [Rational, Integer] the duration of the hold note in beats.
+	# @param text [String] the text to be displayed on the note.
+	# @return [Event] the event representing the hold note.
+	# @raise [ArgumentError] if +x+, +y+, or +duration_beats+ is not a number,
+	#   or if +duration_beats+ is not positive.
+	# @example
+	#   offset 0.1; bpm 120
+	#   h 0, 0, 1, 'Hello'
+	#   h 50, 0, 2, 'world'
+	#   # Now there are two hold notes at (0, 0) and (50, 0)
+	#   # with durations 1 and 2 beats and texts 'Hello' and 'world' respectively
+	def hold x, y, duration_beats, text = ''
+		if !x.is_a?(Numeric) || !y.is_a?(Numeric) || !duration_beats.is_a?(Numeric)
+			raise ArgumentError, 'x, y, and duration must be numbers'
+		end
+		if duration_beats <= 0
+			raise ArgumentError, 'duration must be positive'
+		end
+		if duration_beats.is_a? Float
+			warn 'Rational is recommended over Float for duration_beats'
+		end
+		event :hold, duration_beats.to_r, x: x.to_f, y: y.to_f, text: text.to_s
+	end
+	alias h hold
+
+	# Creates a drag note at the given coordinates.
+	# The coordinates +x+ and +y+ must be numbers.
+	#
+	# Technically, this adds an event of type +:drag+ to the chart at the current time
+	# with properties containing the information provided by +x+ and +y+.
+	# @param x [Numeric] the x-coordinate of the note.
+	# @param y [Numeric] the y-coordinate of the note.
+	# @return [Event] the event representing the drag note.
+	# @raise [ArgumentError] if +x+ or +y+ is not a number.
+	# @example
+	#   offset 0.1; bpm 120
+	#   d 0, 0
+	#   d 50, 0
+	#   # Now there are two drag notes at (0, 0) and (50, 0)
+	def drag x, y
+		if !x.is_a?(Numeric) || !y.is_a?(Numeric)
+			raise ArgumentError, 'x and y must be numbers'
+		end
+		event :drag, x: x.to_f, y: y.to_f
+	end
+	alias d drag
+
+	# Creates a flick note at the given coordinates with the given direction and text.
+	# The coordinates +x+ and +y+ must be numbers.
+	# The argument +direction+ is the direction of the flick note in radians or a symbol.
+	# If it is a symbol, it should be one of the keys of {DIRECTIONS}
+	# (which are +:right+, +:up_right+, etc., abbreviated as +:r+, +:ur+ etc.).
+	# If it is a number, it should be a number representing the angle in radians,
+	# specifying the angle rorated anticlockwise starting from the positive x-direction.
+	# The argument +text+ is the text to be displayed on the note
+	# (it is converted to a string via +to_s+ if it is not a string).
+	#
+	# Technically, this adds an event of type +:flick+ to the chart at the current time
+	# with properties containing the information provided by +x+, +y+, +direction+, and +text+.
+	# @param x [Numeric] the x-coordinate of the note.
+	# @param y [Numeric] the y-coordinate of the note.
+	# @param direction [Numeric, Symbol] the direction of the flick note in radians or a symbol.
+	# @param text [String] the text to be displayed on the note.
+	# @return [Event] the event representing the flick note.
+	# @raise [ArgumentError] if +x+ or +y+ is not a number,
+	#   if +direction+ is not a symbol or a number,
+	#   or if the direction is a symbol that does not represent a known direction.
+	# @example
+	#   offset 0.1; bpm 120
+	#   f 0, 0, :r, 'Hello'
+	#   f 50, 0, Math::PI / 4, 'world'
+	#   # Now there are two flick notes at (0, 0) and (50, 0)
+	#   # with directions right and up right and texts 'Hello' and 'world' respectively
+	def flick x, y, direction, text = ''
+		if !x.is_a?(Numeric) || !y.is_a?(Numeric)
+			raise ArgumentError, 'x and y must be numbers'
+		end
+		if direction.is_a? Symbol
+			direction = DIRECTIONS[direction]
+			raise ArgumentError, "unknown direction #{direction}" unless direction
+		elsif direction.is_a? Numeric
+			warn 'Are you using degrees as angle unit instead of radians?' if direction != 0 && direction % 45 == 0
+			direction = direction.to_f
+		else
+			raise ArgumentError, 'direction must be a symbol or a number'
+		end
+		event :flick, x: x.to_f, y: y.to_f, angle: direction, text: text.to_s
+	end
+	alias f flick
+
+	# Creates a background note at the given coordinates with the given duration and text.
+	# The coordinates +x+ and +y+ must be numbers.
+	# The argument +duration_beats+ is the duration of the background note in beats.
+	# It needs to be a non-negative Rational or Integer.
+	# If it is a Float, it will be converted to a Rational, and a warning will be issued.
+	# The argument +text+ is the text to be displayed on the note
+	# (it is converted to a string via +to_s+ if it is not a string).
+	#
+	# Both the +duration_beats+ and the +text+ arguments are optional.
+	# When there are three arguments given in total,
+	# the method determines whether the third is +duration_beats+ or +text+ based on its type.
+	#
+	# Technically, this adds an event of type +:bg_note+ to the chart at the current time
+	# with properties containing the information provided by +x+, +y+, +duration_beats+, and +text+.
+	# @param x [Numeric] the x-coordinate of the note.
+	# @param y [Numeric] the y-coordinate of the note.
+	# @param duration_beats [Rational, Integer] the duration of the background note in beats.
+	# @param text [String] the text to be displayed on the note.
+	# @return [Event] the event representing the background note.
+	# @raise [ArgumentError] if +x+, +y+, or +duration_beats+ is not a number,
+	#   or if +duration_beats+ is negative.
+	# @example
+	#   offset 0.1; bpm 120
+	#   bg_note 0, 0, 1, 'Hello' # duration is 1, text is 'Hello'
+	#   bg_note 50, 0, 'world'   # duration is 0, text is 'world'
+	#   bg_note -50, 0, 2        # duration is 2, text is ''
+	def bg_note x, y, duration_beats = 0, text = nil
+		if text.nil?
+			if duration_beats.is_a? String
+				text = duration_beats
+				duration_beats = 0
+			else
+				text = ''
+			end
+		end
+		if !x.is_a?(Numeric) || !y.is_a?(Numeric) || !duration_beats.is_a?(Numeric)
+			raise ArgumentError, 'x, y, and duration_beats must be numbers'
+		end
+		if duration_beats < 0
+			raise ArgumentError, 'duration must be non-negative'
+		end
+		if duration_beats.is_a? Float
+			warn 'Rational is recommended over Float for duration_beats'
+		end
+		event :bg_note, duration_beats.to_r, x: x.to_f, y: y.to_f, text: text.to_s
+	end
+
+	# Creates a big text.
+	# The argument +duration_beats+ is the duration of the big text in beats.
+	# It needs to be a non-negative Rational or Integer.
+	# If it is a Float, it will be converted to a Rational, and a warning will be issued.
+	# The argument +text+ is the text to be displayed.
+	#
+	# Technically, this adds an event of type +:big_text+ to the chart at the current time
+	# with properties containing the information provided by +duration_beats+ and +text+.
+	# @param duration_beats [Rational, Integer] the duration of the big text in beats.
+	# @param text [String] the text to be displayed.
+	# @return [Event] the event representing the big text.
+	# @raise [ArgumentError] if +duration_beats+ is not a number or is negative.
+	# @example
+	#   offset 0.1; bpm 120
+	#   big_text 1, 'Hello, world!' # duration is 1, text is 'Hello, world!'
+	#   b 1
+	#   big_text 'Goodbye!'         # duration is 0, text is 'Goodbye!'
+	def big_text duration_beats = 0, text
+		unless duration_beats.is_a? Numeric
+			raise ArgumentError, 'duration_beats must be a number'
+		end
+		if duration_beats < 0
+			raise ArgumentError, 'duration must be non-negative'
+		end
+		if duration_beats.is_a? Float
+			warn 'Rational is recommended over Float for duration_beats'
+		end
+		event :big_text, duration_beats.to_r, text: text.to_s
+	end
+
+	# @!parse
+	#   # @!macro [attach] bg_pattern
+	#   #   @!method $1(duration_beats = 0)
+	#   #   Creates a $2 background pattern.
+	#   #   The argument +duration_beats+ is the duration of the background pattern in beats.
+	#   #   It needs to be a non-negative Rational or Integer.
+	#   #   If it is a Float, it will be converted to a Rational, and a warning will be issued.
+	#   #
+	#   #   Technically, this adds an event of type +:$1+ to the chart at the current time
+	#   #   with properties containing the information provided by +duration_beats+.
+	#   #   @param duration_beats [Rational, Integer] the duration of the background pattern in beats.
+	#   #   @return [Event] the event representing the background pattern.
+	#   #   @raise [ArgumentError] if +duration_beats+ is not a number or is negative.
+	#   #   @example
+	#   #     offset 0.1; bpm 120
+	#   #     $1 1 # duration is 1
+	#   #     b 2
+	#   #     $1 2 # duration is 2
+	#   bg_pattern :grid, 'grid'
+	#   bg_pattern :hexagon, 'hexagon'
+	#   bg_pattern :checkerboard, 'checkerboard'
+	#   bg_pattern :diamond_grid, 'diamond grid'
+	#   bg_pattern :pentagon, 'pentagon'
+	#   bg_pattern :turntable, 'turntable'
+	#   bg_pattern :hexagram, 'hexagram'
+	%i[grid hexagon checkerboard diamond_grid pentagon turntable hexagram].each do |method_name|
+		define_method method_name do |duration_beats = 0|
+			unless duration_beats.is_a? Numeric
+				raise ArgumentError, 'duration_beats must be a number'
+			end
+			if duration_beats < 0
+				raise ArgumentError, 'duration must be non-negative'
+			end
+			if duration_beats.is_a? Float
+				warn 'Rational is recommended over Float for duration_beats'
+			end
+			event method_name, duration_beats.to_r
+		end
+	end
+
+	# @!endgroup
+
+end