sscharter 0.5.4 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 10b5abf2310eeeec8d15d4e26b0bb052057af5a7ec1f8831775fce9c1c824a3e
-  data.tar.gz: edab85fb7449400947f30c182aa4c6be2ce1ba1e968a19a921fdabee4a406ba9
+  metadata.gz: d5b433be7cc354c7fe69d995e2b3713c40eae03f00426b91c5823036e699fa87
+  data.tar.gz: 29697889f1982bef6430b43994543fc27a392752d0937dc490397821107fa98c
 SHA512:
-  metadata.gz: 31f6c6ff5a7fa1eb08af770131617d32dac68d639b63f0d5ac0f6795c0eeaed1b420d206b1c042d7f8e9975c0dc5911b88c595f668765b99e222d010ad4822da
-  data.tar.gz: 5da054dfbf70f06d23eb9b13cccd1efd454f455e9a1fc53c709f959c354acfb2f8ec38b5f6dab164a6cc42e4cfa37612d4836342ef3f9fc2e46e52f786ec2ca3
+  metadata.gz: 3c89b5b04358ab75747fee2d1fb8d1aff7c42b44f99467c1a24da03acf3007df17c2cd1f4a6678ae742145a9fda74a33f21eab0effeefac0984bc0c9eccbe6e5
+  data.tar.gz: a336c573ee240dac57b2d3ab9bdee217fc7f46fdea145058faee8369ca27a8ae0c2503b2d9c01fd5b817288a86159c3d57be385ae25b32bc78d1e0ea2eeefa2f

data/Gemfile

@@ -6,11 +6,13 @@ source "https://rubygems.org"
 gemspec
 
 group :develop do
-	gem "rake", "~> 13.0"
-	gem "minitest", "~> 5.0"
+	gem 'rake', '~> 13.0'
+	gem 'minitest', '~> 5.0'
 end
 
 gem 'rubyzip', '~> 2.3'
 gem 'launchy', '~> 2.5'
 gem 'webrick', '~> 1.8'
 gem 'filewatcher', '~> 2.0'
+gem 'em-websocket', '~> 0.5'
+gem 'concurrent-ruby', '~> 1.3'

data/Gemfile.lock

@@ -1,7 +1,9 @@
 PATH
   remote: .
   specs:
-    sscharter (0.5.4)
+    sscharter (0.6.0)
+      concurrent-ruby (~> 1.3)
+      em-websocket (~> 0.5)
       filewatcher (~> 2.0)
       launchy (~> 2.5)
       rubyzip (~> 2.3)
@@ -10,23 +12,32 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
-    addressable (2.8.6)
-      public_suffix (>= 2.0.2, < 6.0)
+    addressable (2.8.7)
+      public_suffix (>= 2.0.2, < 7.0)
+    concurrent-ruby (1.3.3)
+    em-websocket (0.5.3)
+      eventmachine (>= 0.12.9)
+      http_parser.rb (~> 0)
+    eventmachine (1.2.7)
     filewatcher (2.1.0)
       module_methods (~> 0.1.0)
+    http_parser.rb (0.8.0)
     launchy (2.5.2)
       addressable (~> 2.8)
-    minitest (5.22.3)
+    minitest (5.24.1)
     module_methods (0.1.0)
-    public_suffix (5.0.4)
-    rake (13.1.0)
+    public_suffix (6.0.1)
+    rake (13.2.1)
     rubyzip (2.3.2)
     webrick (1.8.1)
 
 PLATFORMS
+  x64-mingw-ucrt
   x86_64-linux
 
 DEPENDENCIES
+  concurrent-ruby (~> 1.3)
+  em-websocket (~> 0.5)
   filewatcher (~> 2.0)
   launchy (~> 2.5)
   minitest (~> 5.0)
@@ -36,4 +47,4 @@ DEPENDENCIES
   webrick (~> 1.8)
 
 BUNDLED WITH
-   2.5.4
+   2.5.17

data/exe/sscharter

@@ -4,10 +4,9 @@
 require 'sscharter'
 require 'sscharter/cli'
 
-command = ARGV.shift&.to_sym
-unless Sunniesnow::Charter::CLI::COMMANDS.include? command
-	$stderr.puts "Usage: #{File.basename $0} <#{Sunniesnow::Charter::CLI::COMMANDS.join '|'}>"
+unless subcommand = Sunniesnow::Charter::CLI.commands[ARGV.shift&.to_sym]
+	$stderr.puts "Usage: #{File.basename $0} <#{Sunniesnow::Charter::CLI.commands.keys.join '|'}>"
 	exit 1
 end
 
-exit Sunniesnow::Charter::CLI.send(command, *ARGV) || 0
+exit subcommand.run || 0

data/lib/sscharter/chart.rb

@@ -10,7 +10,7 @@ class Sunniesnow::Chart
 	attr_accessor :difficulty_name, :difficulty_color, :difficulty, :difficulty_sup
 	attr_reader :events
 
-	def initialize
+	def initialize live_reload_port: 31108, production: false
 		@title = ''
 		@artist = ''
 		@charter = ''
@@ -19,10 +19,12 @@ class Sunniesnow::Chart
 		@difficulty = ''
 		@difficulty_sup = ''
 		@events = []
+		@live_reload_port = live_reload_port
+		@production = production
 	end
 
 	def to_json *args
-		{
+		hash = {
 			title: @title,
 			artist: @artist,
 			charter: @charter,
@@ -31,7 +33,12 @@ class Sunniesnow::Chart
 			difficulty: @difficulty,
 			difficultySup: @difficulty_sup,
 			events: @events
-		}.to_json
+		}
+		hash[:sscharter] = {
+			version: Sunniesnow::Charter::VERSION,
+			port: @live_reload_port
+		} unless @production
+		hash.to_json
 	end
 end
 

data/lib/sscharter/cli.rb

@@ -3,6 +3,7 @@
 require 'fileutils'
 require 'yaml'
 require 'cgi'
+require 'optparse'
 
 require 'zip'
 require 'launchy'
@@ -10,191 +11,278 @@ require 'webrick'
 require 'filewatcher'
 require 'rake'
 require 'bundler'
+require 'em-websocket'
+require 'concurrent'
 
 require 'sscharter'
 
 module Sunniesnow
 	class Charter
 		module CLI
-		end
-	end
-end
+			module_function
+
+			def config
+				config_filename = File.join PROJECT_DIR, '.sscharter.yml'
+				config_filename = File.join PROJECT_DIR, '.sscharter.yaml' unless File.exist? config_filename
+				unless File.exist? config_filename
+					puts 'No .sscharter.yml found'
+					return nil
+				end
+				YAML.load_file config_filename, symbolize_names: true
+			end
+
+			singleton_class.attr_reader :commands
+			@commands = {}
 
-class Filewatcher
-	# This is a hack. See:
-	# https://github.com/filewatcher/filewatcher/blob/v2.0.0/lib/filewatcher.rb#L42
-	# The `exit` call here will cause the WEBrick server to report a fatal error.
-	def exit
-		stop
+			class Subcommand
+				def initialize name, option_parser, &block
+					@name = name
+					@option_parser = option_parser
+					@block = block
+					CLI.commands[name] = self
+				end
+			
+				def run
+					options = {}
+					@option_parser.parse! into: options
+					@block.(*ARGV, **options)
+				end
+			end
+		end
 	end
 end
 
 module Sunniesnow::Charter::CLI
-	module_function
-
-	COMMANDS = %i[init build serve]
+	module FilewatcherPatch
+		Filewatcher.prepend self
 
-	def config
-		config_filename = '.sscharter.yml'
-		config_filename = '.sscharter.yaml' unless File.exist? config_filename
-		unless File.exist? config_filename
-			puts 'No .sscharter.yml found'
-			return nil
+		# This is a hack. See:
+		# https://github.com/filewatcher/filewatcher/blob/v2.0.0/lib/filewatcher.rb#L42
+		# The `exit` call here will cause the WEBrick server to report a fatal error.
+		def exit
+			stop
 		end
-		YAML.load_file config_filename, symbolize_names: true
 	end
 
-	def init project_dir, *files
-		if File.directory? project_dir
-			puts "Directory #{project_dir} already exists"
-			return 1
-		end
-		files_dir = File.join project_dir, 'files'
-		FileUtils.mkdir_p files_dir
-		FileUtils.cp_r files, files_dir
-		FileUtils.cd project_dir do
-			File.write 'Gemfile', <<~GEMFILE
-				# frozen_string_literal: true
-				source 'https://rubygems.org'
-				gem 'sscharter', '~> #{Sunniesnow::Charter::VERSION}'
-				gem 'rake', '~> #{Rake::VERSION}'
-				gem 'bundler', '~> #{Bundler::VERSION}'
-			GEMFILE
-			File.write 'Rakefile', <<~RAKEFILE
-				# frozen_string_literal: true
-				task default: :build
-				task :build do
-					exec 'bundle exec sscharter build'
-				end
-				task :serve do
-					exec 'bundle exec sscharter serve'
-				end
-			RAKEFILE
-			File.write '.gitignore', <<~GITIGNORE
-				/.bundle/
-				/tmp/
-				/build/
-			GITIGNORE
-			File.write '.sscharter.yml', <<~SSCHARTER
-				---
-				project_name: #{File.basename project_dir}
-				build_dir: build
-				files_dir: files
-				sources_dir: src
-				include:
-				  - README.md
-			SSCHARTER
-			File.write 'README.md', <<~README
-				# #{File.basename project_dir}
-
-				<!-- TODO: Write a description for your project here -->
-
-				## Building
-
-				[Install Ruby (>= 3.0.0)](https://www.ruby-lang.org/en/documentation/installation/),
-				and then run `rake`.
-				The built chart will be `build/#{File.basename project_dir}.ssc`.
-
-				## Legal status
-
-				<!-- The artist should have explicitly stated publicly that they permit charting the music,
-				or have contacted you to give proper permission.
-				Whether or not, you should state clearly the legal status of the chart here. -->
-			README
-			FileUtils.mkdir_p 'src'
-			File.write 'src/master.rb', <<~CHART
-				# frozen_string_literal: true
-
-				Sunniesnow::Charter.open 'master' do
-
-				title 'The title of the music'
-				artist 'The artist of the music'
-				charter 'Your name'
-				difficulty_name 'Master'
-				difficulty_color '#8c68f3'
-				difficulty '12'
-
-				offset 0
-				bpm 120
-
-				tp_chain 0, 0, 1 do
-					t -50, 0, 'hello'
-					b 1 # proceed by 1 beat
-					t 50, 0, 'world'
-				end
+	module OptionParserPatch
+		OptionParser.prepend self
 
-				end
-			CHART
+		def order!(argv = default_argv, into: nil, **keywords, &nonopt)
+			setter = ->(name, val) {into[name.tr(?-, ?_).to_sym] = val} if into
+			parse_in_order(argv, setter, **keywords, &nonopt)
 		end
-		puts "Project initialized at #{project_dir}"
 	end
+end
+
+option_parser = OptionParser.new do |o|
+	o.banner = 'Usage: sscharter init [project_dir] [files...]'
+end
+Sunniesnow::Charter::CLI::Subcommand.new :init, option_parser do |project_dir = Sunniesnow::Charter::PROJECT_DIR, *files|
+	if File.directory?(project_dir) && !Dir.empty?(project_dir)
+		puts "Directory #{project_dir} already exists and is not empty"
+		return 1
+	end
+	files_dir = File.expand_path File.join project_dir, 'files'
+	FileUtils.mkdir_p files_dir
+	FileUtils.cp_r files, files_dir
+	FileUtils.cd project_dir do
+		File.write 'Gemfile', <<~GEMFILE
+			# frozen_string_literal: true
+			source 'https://rubygems.org'
+			gem 'sscharter', '~> #{Sunniesnow::Charter::VERSION}'
+			gem 'rake', '~> #{Rake::VERSION}'
+			gem 'bundler', '~> #{Bundler::VERSION}'
+		GEMFILE
+		File.write 'Rakefile', <<~RAKEFILE
+			# frozen_string_literal: true
+			task default: :build
+			task :build do
+				exec 'bundle exec sscharter build'
+			end
+			task :serve do
+				exec 'bundle exec sscharter serve'
+			end
+		RAKEFILE
+		File.write '.gitignore', <<~GITIGNORE
+			/.bundle/
+			/tmp/
+			/build/
+		GITIGNORE
+		File.write '.sscharter.yml', <<~SSCHARTER
+			---
+			project_name: #{File.basename project_dir}
+			build_dir: build
+			files_dir: files
+			sources_dir: src
+			include:
+			  - README.md
+		SSCHARTER
+		File.write 'README.md', <<~README
+			# #{File.basename project_dir}
+
+			<!-- TODO: Write a description for your project here -->
+
+			## Building
+
+			[Install Ruby (>= 3.0.0)](https://www.ruby-lang.org/en/documentation/installation/),
+			and then run `rake`.
+			The built chart will be `build/#{File.basename project_dir}.ssc`.
+
+			## Legal status
+
+			<!-- The artist should have explicitly stated publicly that they permit charting the music,
+			or have contacted you to give proper permission.
+			Whether or not, you should state clearly the legal status of the chart here. -->
+		README
+		FileUtils.mkdir_p 'src'
+		File.write 'src/master.rb', <<~CHART
+			# frozen_string_literal: true
+
+			Sunniesnow::Charter.open 'master' do
+
+			title 'The title of the music'
+			artist 'The artist of the music'
+			charter 'Your name'
+			difficulty_name 'Master'
+			difficulty_color '#8c68f3'
+			difficulty '12'
+
+			offset 0
+			bpm 120
+
+			tp_chain 0, 0, 1 do
+				t -50, 0, 'hello'
+				b 1 # proceed by 1 beat
+				t 50, 0, 'world'
+			end
+
+			end
+		CHART
+	end
+	puts "Project initialized at #{project_dir}"
+end
 
-	def build
-		return 1 unless config = self.config
-		project_name = config[:project_name] || File.basename(Dir.pwd)
-		build_dir = config[:build_dir] || 'build'
-		files_dir = config[:files_dir] || 'files'
-		sources_dir = config[:sources_dir] || 'src'
-		include_files = config[:include] || []
-		::Sunniesnow::Charter.charts.clear
-		Dir.glob File.join sources_dir, '*.rb' do |filename|
-			load filename
-		rescue Exception => e
-			puts "Error loading #{filename}:"
-			puts e.full_message
-			return 1
+def build **opts
+	return 1 unless config = Sunniesnow::Charter::CLI.config
+	dir = Sunniesnow::Charter::PROJECT_DIR
+	project_name = config[:project_name] || File.basename(dir)
+	build_dir = File.join dir, config[:build_dir] || 'build'
+	files_dir = File.join dir, config[:files_dir] || 'files'
+	sources_dir = File.join dir, config[:sources_dir] || 'src'
+	include_files = (config[:include] || []).map { File.join dir, _1 }
+	Sunniesnow::Charter.charts.clear
+	Dir.glob File.join sources_dir, '*.rb' do |filename|
+		load filename
+	rescue Exception => e
+		puts "Error loading #{filename}:"
+		puts e.full_message
+		return 1
+	end
+	FileUtils.mkdir_p build_dir
+	build_filename = File.join build_dir, "#{project_name}.ssc"
+	FileUtils.rm build_filename if File.exist? build_filename
+	Zip::File.open build_filename, create: true do |zip_file|
+		Dir.glob File.join files_dir, '**', '*' do |filename|
+			zip_file.add filename["#{files_dir}/".length..], filename
 		end
-		FileUtils.mkdir_p build_dir
-		build_filename = File.join build_dir, "#{project_name}.ssc"
-		FileUtils.rm build_filename if File.exist? build_filename
-		Zip::File.open build_filename, create: true do |zip_file|
-			Dir.glob File.join files_dir, '**', '*' do |filename|
-				zip_file.add filename["#{files_dir}/".length..], filename
+		include_files.each do |pattern|
+			Dir.glob pattern do |filename|
+				zip_file.add filename["#{dir}/".length..], filename
 			end
-			include_files.each do |pattern|
-				Dir.glob pattern do |filename|
-					zip_file.add filename, filename
-				end
+		end
+		Sunniesnow::Charter.charts.each do |name, chart|
+			begin
+				output = chart.output_json **opts
+			rescue => e
+				puts 'An error happened. Report if this is a bug of sscharter.'
+				puts e.full_message
+				return 2
 			end
-			::Sunniesnow::Charter.charts.each do |name, chart|
-				begin
-					output = chart.output_json
-				rescue => e
-					puts 'An error happened. Report if this is a bug of sscharter.'
-					puts e.full_message
-					return 2
-				end
-				zip_file.get_output_stream "#{name}.json" do |file|
-					file.write chart.output_json
-				end
+			zip_file.get_output_stream "#{name}.json" do |file|
+				file.write output
 			end
 		end
-		0
 	end
+	0
+end
 
-	def serve port = 8011
-		port = port.to_i
-		config = self.config
-		server = WEBrick::HTTPServer.new Port: port, DocumentRoot: config[:build_dir]
-		def server.service request, response
-			super
-			response['Access-Control-Allow-Origin'] = '*'
-			response['Cache-Control'] = 'no-cache'
-			response['Content-Type'] = 'application/zip' if request.path.end_with? '.ssc'
-		end
-		url = CGI.escape "http://localhost:#{port}/#{config[:project_name]}.ssc"
-		filewatcher = Filewatcher.new [config[:files_dir], config[:sources_dir], *config[:include]]
-		Launchy.open "https://sunniesnow.github.io/game/?level-file=online&level-file-online=#{url}"
-		filewatcher_thread = Thread.new do
-			puts 'Building...'
-			puts build == 0 ? 'Finished' : 'Failed'
-			filewatcher.watch do |changes|
-				puts 'Rebuilding...'
-				puts build == 0 ? 'Finished' : 'Failed'
+option_parser = OptionParser.new do |o|
+	o.banner = 'Usage: sscharter build'
+end
+Sunniesnow::Charter::CLI::Subcommand.new :build, option_parser do
+	build production: true
+end
+
+option_parser = OptionParser.new do |o|
+	o.banner = 'Usage: sscharter serve [options]'
+	o.on '--host=HOST', String, 'Host name'
+	o.on '--exposed-host=HOST', String, 'Exposed host name'
+	o.on '--port=PORT', Integer, 'Port number'
+	o.on '--live-reload-port=PORT', Integer, 'live reload port number'
+	o.on '--[no-]production', 'Disable live reload'
+	o.on '--[no-]open-browser', 'Open browser'
+end
+Sunniesnow::Charter::CLI::Subcommand.new :serve, option_parser do |host: '0.0.0.0', exposed_host: 'localhost', port: 8011, live_reload_port: 31108, production: false, open_browser: true|
+	return 1 unless config = Sunniesnow::Charter::CLI.config
+	dir = Sunniesnow::Charter::PROJECT_DIR
+	project_name = config[:project_name] || File.basename(dir)
+	build_dir = File.join dir, config[:build_dir] || 'build'
+	files_dir = File.join dir, config[:files_dir] || 'files'
+	sources_dir = File.join dir, config[:sources_dir] || 'src'
+	include_files = (config[:include] || []).map { File.join dir, _1 }
+	server = WEBrick::HTTPServer.new BindAddress: host, Port: port, DocumentRoot: build_dir
+	def server.service request, response
+		super
+		response['Access-Control-Allow-Origin'] = '*'
+		response['Cache-Control'] = 'no-cache'
+		response['Content-Type'] = 'application/zip' if request.path.end_with? '.ssc'
+	end
+	unless production
+		live_reload_clients = Concurrent::Array.new
+		Thread.new do
+			EM.run do
+				EM::WebSocket.run host:, port: live_reload_port do |ws|
+					ws.onopen do
+						live_reload_clients.push ws
+					end
+					ws.onclose do
+						live_reload_clients.delete ws
+					end
+					ws.onmessage do |message|
+						data = JSON.parse message, symbolize_names: true
+						case data[:type]
+						when 'connect'
+							puts "Connected: #{data[:userAgent]}"
+						when 'eventInfoTip'
+							if backtrace = Sunniesnow::Charter.charts[File.basename data[:chart], '.*']&.events[data[:id]]&.backtrace
+								puts "Event #{data[:id]} in #{data[:chart]} was defined at"
+								puts backtrace
+							else
+								puts "Event #{data[:id]} in #{data[:chart]} is not found"
+							end
+						else
+							puts "Unknown message type '#{data[:type]}' from live reload client"
+						end
+					end
+				end
 			end
-			server.shutdown
 		end
-		server.start
-		0
 	end
+	url = "http://#{exposed_host}:#{port}/#{project_name}.ssc"
+	filewatcher = Filewatcher.new [files_dir, sources_dir, *include_files]
+	Launchy.open "https://sunniesnow.github.io/game/?level-file=online&level-file-online=#{CGI.escape url}" if open_browser
+	build_proc = ->is_first do
+		puts is_first ? 'Building...' : 'Rebuilding...'
+		success = build(live_reload_port:, production:) == 0
+		puts success ? is_first ? "Finished; access at #{url}" : 'Finished' : 'Failed'
+		live_reload_clients.each { _1.send JSON.generate type: 'update' } unless production
+	end
+	filewatcher_thread = Thread.new do
+		build_proc.(true)
+		filewatcher.watch { |changes| build_proc.(false) }
+		server.shutdown
+		EM.stop unless production
+	end
+	server.start
+	0
 end

data/lib/sscharter/version.rb

@@ -2,6 +2,6 @@
 
 module Sunniesnow
 	class Charter
-		VERSION = "0.5.4"
+		VERSION = "0.6.0"
 	end
 end

data/lib/sscharter.rb

@@ -6,6 +6,8 @@ require_relative 'sscharter/chart'
 
 class Sunniesnow::Charter
 
+	PROJECT_DIR = File.expand_path(ENV['SSCHARTER_PROJECT_DIR'] ||= Dir.pwd)
+
 	using Sunniesnow::Utils
 
 	class OffsetError < StandardError
@@ -71,7 +73,7 @@ class Sunniesnow::Charter
 		TIP_POINTABLE_TYPES = %i[tap hold flick drag]
 
 		attr_accessor :beat, :offset, :duration_beats, :properties
-		attr_reader :type, :bpm_changes
+		attr_reader :type, :bpm_changes, :backtrace
 
 		def initialize type, beat, duration_beats = nil, bpm_changes, **properties
 			@beat = beat
@@ -80,6 +82,7 @@ class Sunniesnow::Charter
 			@bpm_changes = bpm_changes
 			@properties = properties
 			@offset = 0.0
+			@backtrace = caller.filter { _1.sub! /^#{PROJECT_DIR}\//, '' }
 		end
 
 		def time_at_relative_beat delta_beat
@@ -118,6 +121,11 @@ class Sunniesnow::Charter
 		def tip_pointable?
 			TIP_POINTABLE_TYPES.include? @type
 		end
+
+		def inspect
+			"#<#@type at #@beat#{@duration_beats && " for #@duration_beats"} offset #@offset: " +
+			@properties.map { |k, v| "#{k}=#{v.inspect}" }.join(', ') + '>'
+		end
 	end
 
 	# Implements homography
@@ -304,6 +312,8 @@ class Sunniesnow::Charter
 	singleton_class.attr_reader :charts
 	@charts = {}
 
+	attr_reader :events
+
 	def self.open name, &block
 		result = @charts[name] ||= new name
 		result.instance_eval &block if block
@@ -333,6 +343,7 @@ class Sunniesnow::Charter
 		@bpm_changes = nil
 		@tip_point_mode_stack = [:none]
 		@current_tip_point_stack = []
+		@current_tip_point_group_stack = []
 		@tip_point_peak = 0
 		@current_duplicate = 0
 		@tip_point_start_to_add_stack = [nil]
@@ -431,26 +442,12 @@ class Sunniesnow::Charter
 		@bpm_changes.time_at beat
 	end
 
-	def tip_point_chain *args, preserve_beat: true, **opts, &block
-		tip_point :chain, *args, **opts do
-			group preserve_beat: preserve_beat, &block
-		end#.tap { @tip_point_peak += 1 }
-	end
-	alias tp_chain tip_point_chain
-
-	def tip_point_drop *args, preserve_beat: true, **opts, &block
-		tip_point :drop, *args, **opts do
-			group preserve_beat: preserve_beat, &block
+	%i[chain drop none].each do |mode|
+		define_method "tip_point_#{mode}" do |*args, **opts, &block|
+			tip_point mode, *args, **opts, &block
 		end
+		alias_method "tp_#{mode}", "tip_point_#{mode}"
 	end
-	alias tp_drop tip_point_drop
-
-	def tip_point_none preserve_beat: true, &block
-		tip_point :none do
-			group preserve_beat: preserve_beat, &block
-		end
-	end
-	alias tp_none tip_point_none
 
 	def group preserve_beat: true, &block
 		raise ArgumentError, 'no block given' unless block
@@ -470,7 +467,7 @@ class Sunniesnow::Charter
 		result
 	end
 
-	def tip_point mode, *args, **opts, &block
+	def tip_point mode, *args, preserve_beat: true, **opts, &block
 		@tip_point_mode_stack.push mode
 		if mode == :none
 			@current_tip_point_stack.push nil
@@ -479,13 +476,21 @@ class Sunniesnow::Charter
 			@current_tip_point_stack.push @tip_point_peak
 			@tip_point_peak += 1
 		end
-		result = block.()
+		result = group preserve_beat: do
+			@current_tip_point_group_stack.push @groups.last
+			instance_eval &block
+		end
 		@tip_point_start_to_add_stack.pop
 		@tip_point_mode_stack.pop
 		@current_tip_point_stack.pop
+		@current_tip_point_group_stack.pop
 		result
 	end
 
+	def remove *events
+		events.each { @events.delete _1 }
+	end
+
 	def event type, duration_beats = nil, **properties
 		raise OffsetError.new __method__ unless @bpm_changes
 		event = Event.new type, @current_beat, duration_beats, @bpm_changes, **properties
@@ -508,7 +513,11 @@ class Sunniesnow::Charter
 	def push_tip_point_start start_event
 		start_event[:tip_point] = @current_tip_point_stack.last.to_s
 		tip_point_start = @tip_point_start_to_add_stack.last&.get_start_placeholder start_event
-		@groups.each { _1.push tip_point_start } if tip_point_start
+		return unless tip_point_start
+		@groups.each do |group|
+			group.push tip_point_start
+			break if group.equal?(@current_tip_point_group_stack.last) && @tip_point_mode_stack.last != :drop
+		end
 	end
 
 	def transform events, &block
@@ -629,8 +638,8 @@ class Sunniesnow::Charter
 		end
 	end
 
-	def to_sunniesnow
-		result = Sunniesnow::Chart.new
+	def to_sunniesnow **opts
+		result = Sunniesnow::Chart.new **opts
 		result.title = @title
 		result.artist = @artist
 		result.charter = @charter
@@ -642,8 +651,12 @@ class Sunniesnow::Charter
 		result
 	end
 
-	def output_json
-		to_sunniesnow.to_json
+	def output_json **opts
+		to_sunniesnow(**opts).to_json
+	end
+
+	def inspect
+		"#<Sunniesnow::Charter #@name>"
 	end
 
 end

data/tutorial/tutorial.md

@@ -212,38 +212,171 @@ This command will open the Sunniesnow webpage in your browser for you.
 The `online` field of Sunniesnow is already filled with the address to the generated level file.
 Every time you save changes to the source codes,
 the program will automatically rebuild the level file.
-You just need to hit "load" again to reload the level file.
+Sunniesnow will reload the level file automatically if you are using the default settings.
 
 The port of the local server is 8011 by default.
 If you need to change the port to 1314 for example, you need to run
 
 ```shell
-bundle exec sscharter serve 1314
+bundle exec sscharter serve --port 1314
 ```
 
+You can edit `Rakefile` to make `rake serve` use that port.
+
 > [!TIP]
-> The default settings of Sunniesnow are tuned for gameplay instead of charting,
-> so you may want to change some settings to help you write the chart.
-> Here are some useful settings:
+> If you do not even want the live reload feature,
+> you can turn it off by using
+>
+> ```shell
+> bundle exec sscharter serve --production
+> ```
 >
-> - Enable [`autoplay`](https://sunniesnow.github.io/game/help.html#autoplay).
-> - Disable [`fullscreen-on-start`](https://sunniesnow.github.io/game/help.html#fullscreen-on-start).
->   Fullscreen is good for gamplay but is disturbing for charting.
-> - Enable [`debug`](https://sunniesnow.github.io/game/help.html#debug),
->   and you can see the current progress of the music, the judgement region of notes,
->   the coordinates of where you click your mouse, etc.
-> - Use the option [`start`](https://sunniesnow.github.io/game/help.html#start)
->   to start the music at a certain time.
->   You can use the progress you got from debug mode UI to set it.
-> - Enable [`se-with-music`](https://sunniesnow.github.io/game/help.html#se-with-music)
->   and set [`chart-offset`](https://sunniesnow.github.io/game/help.html#chart-offset) to zero.
->   This will make sure the timing of sound effects is precise no matter how much latency your computer has.
+> This way, the level file generated is the same as that generated by `sscharter build`,
+> which does not contain the info necessary for live reload.
+
+### Configure Sunniesnow to suit charting
+
+The default settings of Sunniesnow are tuned for gameplay instead of charting,
+so you may want to change some settings to help you write the chart.
+Use this link to set these settings quickly:
+
+https://sunniesnow.github.io/game/?volume-se=1&se-with-music=true&chart-offset=0&autoplay=true&progress-adjustable=true&hide-pause-ui=true&resume-preparation-time=0&always-update-fx=true&debug=true&fullscreen-on-start=false&sscharter=true&sscharter-live-restart=true
+
+First, the most important part of rhythm game charting is to ensure that notes are pefectly aligned with the music.
+To help you with that, configure the following settings:
+
+- set [`volume-se`](https://sunniesnow.github.io/game/help.html#volume-se) to a proper positive value,
+- enable [`se-with-music`](https://sunniesnow.github.io/game/help.html#se-with-music), and
+- set [`chart-offset`](https://sunniesnow.github.io/game/help.html#chart-offset) to `0` (this is default).
+
+You can still set [`delay`](https://sunniesnow.github.io/game/help.html#delay)
+and [`offset`](https://sunniesnow.github.io/game/help.html#offset)
+to fit the audio and display latency of your device.
+You can still ensure the notes are aligned with the music by listening to the sound effects.
+To learn what the differences between these two settings and `chart-offset`,
+read [differences between different offsets](https://sunniesnow.github.io/game/help.html#differences-between-different-offsets).
+
+Configure the following settings to have a video-player-like experience:
+
+- enable [`autoplay`](https://sunniesnow.github.io/game/help.html#autoplay),
+- enable [`progress-adjustable`](https://sunniesnow.github.io/game/help.html#progress-adjustable),
+- enable [`hide-pause-ui`](https://sunniesnow.github.io/game/help.html#hide-pause-ui),
+- enable [`always-update-fx`](https://sunniesnow.github.io/game/help.html#always-update-fx), and
+- set [`resume-preparation-time`](https://sunniesnow.github.io/game/help.html#resume-preparation-time) to `0`.
+
+You can drag the progress bar or hit <kbd>ArrowLeft</kbd>
+or <kbd>ArrowRight</kbd> to adjust the progress.
+See the help contents of [`progress-adjustable`](https://sunniesnow.github.io/game/help.html#progress-adjustable)
+to learn other controls available in this mode.
+
+Enable [`debug`](https://sunniesnow.github.io/game/help.html#debug),
+and you can see the current progress of the music, the judgement region of notes,
+the coordinates of where you click your mouse, etc.
+You can also pin coordinates on the screen by clicking while holding <kbd>Ctrl</kbd>.
+Other controls for pinning coordinates in this mode are introduced in the help contents of
+[`debug`](https://sunniesnow.github.io/game/help.html#debug).
+When the game is paused in debug mode, you can also click
+a note, background note, or background pattern to reveal the event details,
+including the event ID, its time and properties, and (if it is a note) which combo number it is at.
+The most useful feature of the debug mode for charting with sscharter is that,
+if the chart you are playing is served by sscharter (without the `--production` flag),
+the sscharter server will tell you (in the terminal) where the event is defined
+when you reveal the event details in Sunniesnow.
+This gives the ability of reverse searching.
+
+Finally, although it is already convenient to have the level file
+reloaded automatically when you save changes to the source codes,
+you can enable [`sscharter-live-restart`](https://sunniesnow.github.io/game/help.html#sscharter-live-restart)
+to make it more convenient.
+This setting will make the game restarted automatically when you save changes to the source codes.
+
+Other useful settings:
+
+- Disable [`fullscreen-on-start`](https://sunniesnow.github.io/game/help.html#fullscreen-on-start).
+  Fullscreen is good for gamplay but is disturbing for charting.
+- Use the option [`start`](https://sunniesnow.github.io/game/help.html#start)
+  to start the music at a certain time.
+  You can use the progress you got from debug mode UI to set it.
+
+### Text editor configuration
+
+The workflow can be enhanced with a good text editor.
+Here is a setup with Visual Studio Code
+(abbreviated as VS Code in the following) without any external extensions.
+
+Create a file `.vscode/tasks.json` in your project and write:
+
+```json
+{
+    "version": "2.0.0",
+    "tasks": [
+        {
+            "label": "Serve",
+            "type": "shell",
+            "command": "rake serve",
+            "presentation": {
+                "reveal": "always"
+            }
+        },
+        {
+            "label": "Build",
+            "type": "shell",
+            "command": "rake build",
+            "group": "build"
+        }
+    ]
+}
+```
+
+Then, edit `Rakefile` to disable browser launching and enable live restart:
+
+```ruby
+task :serve do
+  exec 'bundle exec sscharter serve --no-open-browser --live-restart'
+end
+```
+
+Hit <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd> in VS Code,
+type "Simple Browser", and you will see an option to open a webpage using
+the simple browser feature of VS Code.
+Select that option, and then there is a popup telling you to enter the web address.
+Type "https://sunniesnow.github.io/game"
+(or the very long link that sets all the settings for charting quickly shown
+[above](#configure-sunniesnow-to-suit-charting)) and then enter.
+After that, drag the simple browser tab to make it alongside with the main editor
+(the split editor feature of VS Code).
+
+Then, hit <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd> and type "Run Task".
+There is an option with which you can run a task configured in `.vscode/tasks.json`.
+Select that option, and then select the "Serve" task.
+(After that, VS Code asks you whether to scan the output. You can skip that.)
+A new widget will open in the bottom (the integrated terminal feature of VS Code)
+showing the terminal output of sscharter.
+After sscharter finishes building the level file, a URL to the level file will be shown.
+Copy that URL into the
+[`level-file-online`](https://sunniesnow.github.io/game/help.html#level-file-online) setting.
+Then, hit the start button in Sunniesnow to check that you can play the chart.
+
+After that, configure Sunniesnow to suit charting as described
+[above](#configure-sunniesnow-to-suit-charting).
+You now have a decent charting setup.
+
+When you want to reverse search an event, you can pause the game in debug mode
+and click the event (note, background note, or background pattern).
+You can then see the its definition location in the terminal output below.
+In VS Code, you can navigate to the location in the editor
+by clicking the file path and line number in the terminal output
+while holding <kbd>Ctrl</kbd> (or other modifier keys depending on your configuration).
+
+The following is a screenshot of the setup:
+
+![VS Code setup](https://i.imgur.com/O3nhKX4.png)
 
 ## What does each line in `src/master.rb` mean?
 
 Now, you are ready to write the chart!
 Open `src/master.rb` using your text editor.
-Here I explain what does each line mean.
+Here I explain what each line in this file means.
 
 ```ruby
 Sunniesnow::Charter.open 'master' do
@@ -271,7 +404,7 @@ difficulty_sup '+' # optional
 ```
 
 These lines are the metadata of the chart.
-They already explains pretty much themselves.
+They already explain pretty much themselves.
 Just fill them in!
 
 By the way, there is a trick about the `difficulty_color` for your convenience.
@@ -1064,6 +1197,22 @@ TODO.
 
 ### Use Git as a version manager
 
+You ever want to keep track of the changes you made to the chart?
+You ever wish to revert to a previous version of the chart?
+You ever want to collaborate with others on the chart?
+You can use [Git](https://git-scm.com/) to implement these version control features.
+
+First, install Git.
+Then, run `git init` in your project directory to make it a Git repository.
+Every time you want to save the current version of the chart,
+you can run `git add .` to stage all the changes,
+and then run `git commit -m "Your commit message here"` to commit the changes.
+Git may prompt you to set up your name and email address,
+then just do so by following the instructions.
+
+A detailed tutorial on how to use Git is beyond the scope of this tutorial,
+so I may just refer you to the official [tutorial](https://git-scm.com/docs/gittutorial) of Git.
+
 ### Useful loops
 
 ### Homography

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sscharter
 version: !ruby/object:Gem::Version
-  version: 0.5.4
+  version: 0.6.0
 platform: ruby
 authors:
 - Ulysses Zhan
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-03-23 00:00:00.000000000 Z
+date: 2024-08-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rubyzip
@@ -66,6 +66,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: em-websocket
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.5'
+- !ruby/object:Gem::Dependency
+  name: concurrent-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
@@ -135,7 +163,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.22
+rubygems_version: 3.5.9
 signing_key:
 specification_version: 4
 summary: A Ruby DSL for writing Sunniesnow charts