social-game-kit 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 65571e588b48927227617f828d9f137a8266e8d84f2720ae4025efa5b20f97c1
+  data.tar.gz: 15473e8e6a643022c099bfc04cceb8f3c19486395ea6a3f31b98ae44d301571a
+SHA512:
+  metadata.gz: b681aed93bc74186fb42e9a27a745ef720c21522aba4733c7852ff46dcc5649574fbf6ea555da85364beac0795ca372a5d37ac0383eaba6ab10ba6b13c59f3b0
+  data.tar.gz: 21e9ea9293a84a29eb1ad2dcc7a9757caf1b8d04181c38b3f8d1fe2b8d71e7829f6d9e92c55bc7b4b46b785f6cf013a08da75dc26e8df1957bfa404c0ad79bdf

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,20 @@
+AllCops:
+  TargetRubyVersion: 3.1
+  NewCops: enable
+  SuggestExtensions: false
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes
+
+# テスト用の簡易モデルなのでドキュメント不要
+Style/Documentation:
+  Exclude:
+    - "spec/**/*"
+
+# ブロック長は指定しない
+Metrics/BlockLength:
+  Exclude:
+    - "spec/**/*"

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2025-11-02
+
+- Initial release

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 NYUWAMOCHI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 sugawara_nagisa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,296 @@
+# Social Game Kit
+
+Ruby on Railsアプリケーション向けのソーシャルゲーム機能を提供するgemです。
+重み付き確率に基づくガチャ機能を実装しており、メモリ効率を考慮した設計になっています。
+
+## 機能
+
+- 重み付きガチャ機能
+- 確率計算機能
+- 単発・複数回ガチャ対応（10連ガチャ等）
+
+## インストール
+
+Gemfileに以下を追加：
+
+```ruby
+gem 'social-game-kit'
+```
+
+その後、以下を実行：
+
+```bash
+bundle install
+```
+
+## 要件
+
+- Ruby 3.1.0以上
+- Rails 6.0以上
+- ActiveRecord
+- ActiveSupport
+
+## 使用方法
+
+### 基本的な使用方法
+
+```ruby
+require 'sgk'
+
+# カードマスタデータ（ActiveRecordモデル）から抽選
+cards = GachaCard.all
+
+# エンジンの初期化
+engine = SGK::Gacha::Engine.new(cards)
+
+# 単発抽選
+card = engine.draw
+puts card.name    # => "コモン" など
+puts card.rarity  # => "common"
+
+# 複数回抽選（10連ガチャ）
+results = engine.draw_multiple(10)
+puts results.size # => 10
+
+# 確率の計算
+probabilities = engine.probabilities
+# => {1=>70.0, 2=>25.0, 3=>4.0, 4=>1.0}
+```
+
+### Railsアプリケーションでの例
+
+```ruby
+# app/models/gacha_card.rb
+class GachaCard < ApplicationRecord
+  validates :name, :rarity, :weight, presence: true
+  validates :weight, numericality: { greater_than: 0 }
+
+  enum rarity: {
+    common: 0,
+    rare: 1,
+    super_rare: 2,
+    ultra_rare: 3
+  }
+end
+
+# app/controllers/gacha_controller.rb
+class GachaController < ApplicationController
+  def draw
+    engine = SGK::Gacha::Engine.new(GachaCard.all)
+    @result = engine.draw
+
+    # ユーザーにカードを付与する処理など
+    current_user.gacha_cards << @result
+
+    render json: @result.json_format
+  end
+
+  def draw_multiple
+    count = params[:count].to_i.clamp(1, 10)  # 最大10連
+    engine = SGK::Gacha::Engine.new(GachaCard.all)
+    @results = engine.draw_multiple(count)
+
+    current_user.gacha_cards.push(*@results)
+
+    render json: {
+      cards: @results.map(&:json_format)
+    }
+  end
+
+  def probabilities
+    engine = SGK::Gacha::Engine.new(GachaCard.all)
+
+    render json: engine.probabilities
+  end
+end
+```
+
+### ガチャカードモデルの例
+
+```ruby
+# db/migrate/20240101000000_create_gacha_cards.rb
+class CreateGachaCards < ActiveRecord::Migration[7.0]
+  def change
+    create_table :gacha_cards do |t|
+      t.string :name, null: false
+      t.string :rarity, null: false
+      t.integer :weight, null: false, default: 1
+      t.text :description
+      t.string :image_url
+
+      t.timestamps
+    end
+
+    add_index :gacha_cards, :rarity
+    add_index :gacha_cards, :weight
+  end
+end
+
+# db/seeds.rb
+GachaCard.create!([
+  { name: "コモンカード", rarity: :common, weight: 70 },
+  { name: "レアカード", rarity: :rare, weight: 25 },
+  { name: "スーパーレアカード", rarity: :super_rare, weight: 4 },
+  { name: "ウルトラレアカード", rarity: :ultra_rare, weight: 1 }
+])
+```
+
+## 重み付き抽選アルゴリズム
+
+このgemは累積重み方式を使用して、効率的にカードを抽選します。
+
+### アルゴリズムの説明
+
+1. 全カードの重みを合計（total_weight）
+2. 0〜total_weightの範囲でランダム値を生成
+3. 累積重みを計算しながら、ランダム値が該当する範囲のカードを選択
+
+### 例
+
+```
+カードA: 重み70 (累積: 0-69)
+カードB: 重み25 (累積: 70-94)
+カードC: 重み4  (累積: 95-98)
+カードD: 重み1  (累積: 99)
+合計: 100
+
+ランダム値75 → カードBを選択
+```
+
+## APIリファレンス
+
+### SGK::Gacha::Engine
+
+#### `initialize(card_relation)`
+
+ActiveRecord::Relationを受け取ります。
+
+```ruby
+engine = SGK::Gacha::Engine.new(GachaCard.all)
+```
+
+#### `draw`
+
+単発ガチャを実行し、カードを返します。
+
+```ruby
+card = engine.draw
+```
+
+#### `draw_multiple(count)`
+
+複数回ガチャを実行します。countは正の整数である必要があります。
+
+```ruby
+cards = engine.draw_multiple(10)  # 10連ガチャ
+```
+
+#### `probabilities`
+
+各カードの確率（パーセント）をハッシュで返します。
+
+```ruby
+probs = engine.probabilities
+# => {1=>70.0, 2=>25.0, 3=>4.0, 4=>1.0}
+```
+
+### SGK::Gacha::Result
+
+ガチャ結果をラップするクラスです。
+
+#### `card`
+
+抽選されたカードオブジェクトを返します（読み取り専用）。
+
+#### `name`
+
+カード名を返します。
+
+#### `rarity`
+
+カードのレア度を返します。
+
+#### `json_format`
+
+カード情報をハッシュで返します（JSON化用）。
+
+```ruby
+result = engine.draw
+result.json_format
+# => { card_id: 1, name: "コモン", rarity: "common" }
+```
+
+## メモリ効率について
+
+このgemの`probabilities`メソッドはハッシュを使用しており、実際に存在するカードのIDだけを保存します。
+IDが飛び飛びの場合（例: 1-100と1000-10000）でも、間のIDのエントリは作成されません。
+
+⚠️ **配列を使った場合の問題**
+
+```ruby
+# ❌ 配列を使った実装（メモリを大量に消費）
+arr = []
+arr[1000] = "value"
+# インデックス0-999もメモリに確保される
+```
+
+このgemはハッシュを使用することでこの問題を回避しています。
+
+## 開発
+
+リポジトリをクローンした後：
+
+```bash
+bundle install
+```
+
+テストを実行：
+
+```bash
+bundle exec rspec
+```
+
+コード品質をチェック：
+
+```bash
+bundle exec rubocop
+```
+
+対話的なプロンプトで実験：
+
+```bash
+bin/console
+```
+
+gemをローカルにインストール：
+
+```bash
+bundle exec rake install
+```
+
+## テスト
+
+このgemは包括的なテストスイートを含みます。
+
+```bash
+# 全テスト実行
+bundle exec rake
+
+# RSpecのみ実行
+bundle exec rspec
+
+# RuboCopのみ実行
+bundle exec rubocop
+```
+
+## 貢献
+
+バグレポートやプルリクエストはGitHubで歓迎します。
+
+https://github.com/NYUWAMOCHI/social-game-kit
+
+## ライセンス
+
+このgemは[MIT License](https://opensource.org/licenses/MIT)の下でオープンソースとして利用可能です。
+
+詳細は[LICENSE.txt](LICENSE.txt)を参照してください。

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/sgk/gacha/engine.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module SGK
+  module Gacha
+    # Gacha engine that implements weighted random card selection.
+    #
+    # This engine takes an ActiveRecord relation of cards and provides methods
+    # to draw cards based on their weights, supporting both single draws and
+    # multiple draws in one operation.
+    class Engine
+      def initialize(card_relation)
+        @cards = card_relation.to_a
+        validate_cards!
+        @total_weight = @cards.sum(&:weight)
+      end
+
+      def draw
+        return nil if @cards.empty?
+
+        random_value = rand(0...@total_weight)
+        current_sum = 0
+
+        @cards.each do |card|
+          current_sum += card.weight
+          return card if random_value < current_sum
+        end
+
+        # NOTE: 浮動小数点誤差を考慮して最後のカードを返す実装だが、重み付き抽選の特性上起こる可能性はほとんどない。
+        # Returns the last card as a fallback for floating-point precision errors,
+        # though this scenario is highly unlikely given the nature of weighted random selection.
+        @cards.last
+      end
+
+      # Draw multiple cards in a single operation (e.g., 10-draw gacha).
+      #
+      # @param count [Integer] Number of cards to draw
+      # @return [Array<Object>] Array of drawn cards
+      # @raise [ArgumentError] If count is not positive
+      def draw_multiple(count)
+        raise ArgumentError, "Draw count must be positive" unless count.positive?
+
+        Array.new(count) { draw }
+      end
+
+      def probabilities
+        result = {}
+        @cards.each do |card|
+          result[card.id] = (card.weight.to_f / @total_weight * 100).round(2)
+        end
+        result
+      end
+
+      private
+
+      def validate_cards!
+        raise ArgumentError, "Cards cannot be empty" if @cards.empty?
+        raise ArgumentError, "All cards must respond to :weight" unless @cards.all? { |card| card.respond_to?(:weight) }
+        raise ArgumentError, "All weights must be positive" unless @cards.all? { |card| card.weight.positive? }
+      end
+    end
+  end
+end

data/lib/sgk/gacha/result.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module SGK
+  module Gacha
+    # Represents the result of a gacha draw.
+    #
+    # This class wraps a card object and provides convenient accessors
+    # for common card properties. It can be serialized to a hash for
+    # logging or API responses.
+    class Result
+      attr_reader :card
+
+      def initialize(card)
+        @card = card
+      end
+
+      def name
+        @card.name
+      end
+
+      def rarity
+        @card.rarity
+      end
+
+      # Convert the result to a hash for JSON serialization.
+      #
+      # @return [Hash] A hash containing card_id, name, and rarity
+      def json_format
+        {
+          card_id: @card.id,
+          name: @card.name,
+          rarity: @card.rarity
+        }
+      end
+    end
+  end
+end

data/lib/sgk/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module SGK
+  VERSION = "0.1.0"
+end

data/lib/sgk.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "sgk/version"
+require_relative "sgk/gacha/engine"
+require_relative "sgk/gacha/result"
+
+module SGK
+  class Error < StandardError; end
+end

data/sig/ssg.rbs

@@ -0,0 +1,4 @@
+module Ssg
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,84 @@
+--- !ruby/object:Gem::Specification
+name: social-game-kit
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- sugawara_nagisa
+bindir: exe
+cert_chain: []
+date: 2025-11-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+description: Rails向けソーシャルゲーム機能kit。重み付きガチャエンジンなど
+email:
+- nyuwamochi@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- CHANGELOG.md
+- LICENSE
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/sgk.rb
+- lib/sgk/gacha/engine.rb
+- lib/sgk/gacha/result.rb
+- lib/sgk/version.rb
+- sig/ssg.rbs
+homepage: https://github.com/NYUWAMOCHI/social-game-kit
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/NYUWAMOCHI/social-game-kit
+  source_code_uri: https://github.com/NYUWAMOCHI/social-game-kit
+  changelog_uri: https://github.com/NYUWAMOCHI/social-game-kit/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: Social Game Kit for Ruby on Rails
+test_files: []