#============================================================================
#
#　■アクター毎のアイテム所持・マニュアル スクリプト編　　□製作者：月紳士
#　・RPGツクールVX用 RGSS2スクリプト
#
#  ※二次配布禁止！配布元には利用規約があります。必ずそちらを見てください。
#============================================================================
=begin

  アクター毎のアイテム所持のマニュアルです。
　このマニュアルは「スクリプト編」として、
　イベントコマンド・スクリプトなどに記述する
　スクリプトコマンドについて説明しています。

　ある程度のスクリプト知識を必要とします。中級〜上級者向けに書いていますが、
　初心者でもわからない点をネット検索などしていただければ充分扱えると思います。

　　※ スクリプト、RGSS、Rubyに関する知識を、
　　　 月紳士で事細かに説明することは出来ません。
　　　 当スクリプトの月紳士しか知りえないことに関しては
　　　 その質問に進んでお答えしたいと思いますが、
　　　 それ以外は、ネット検索などで独学されることをお勧めします。

　基本的な使い方に関しては「マニュアル・基本編」をご覧下さい。
　一部のコマンドは基本編で説明しています。
　　

　内容が長いので項目で分けています。項目の頭に ● を付けているので
　文章内検索をつかってページ替わりにしてお使い下さい。

　※ このマニュアルは素材としてプロジェクト内に貼り付ける事も可能です。


== ●所持品の情報取得 =======================================================

　このシステムでは
　プレーヤーが自由にアクター間で所持品を行き来させることが出来たり、
　任意に破棄したり預けたりと出来る為、所持品の有無や数の違い等、
　アクター毎に様々な状況がありえます。　

　イベントコマンド・スクリプトにて次のような記述をつかって、
　それらのうちから必要な情報を取得します。

　※　以下のスクリプトにて、things(kind, id) と表記された部分は
　　　そのまま記述するのではなく、
      kind、id それぞれ、任意の数に置き換えて記述してください。
      
    　所持品にはアイテムだけでなく、武器、防具も含まれる為、
    　IDだけでなく、アイテムか、武器か、といったことを、kindで指定します。
    
    　kind は種別です。アイテムなら 0 、武器なら 1 防具なら 2 です。
    　ID 6 番の武器であれば things以降の括弧内の kind、id の部分を 
      things(1, 6) というように置き換えます。
    
  取得した所持品情報は、主に条件分岐・スクリプトで使用されるでしょう。
    
--- ○指定の品を持っているか？ ----------------------------------------------

　指定の品を持っているか、否かを判定します。
　いくつかスクリプトをあげますが、いずれも
　所持していれば true を、所持していなければ false を返します。

　ひとりのアクターを指定して、
　そのアクターが指定の品を所持しているか判定するには以下を記述します。
　(actor_id の部分には任意のアクターIDを記入してください)

$game_actors[actor_id].carrying_item?( things(kind, id) )


　袋の中に指定の品があるか判定する場合が以下です。

$game_party.carrying_item?( things(kind, id) )

　
　パーティー全体で、指定の品を所持しているか判定するには以下です。

$game_party.has_item?( things(kind, id) )


　アクター全体で、指定の品を所持しているか判定するには以下です。

$game_actors.has_item?( things(kind, id) )


--- ○指定の品を誰が所持しているか？ ----------------------------------------

　指定の品を、誰が所持しているかをアクター全体から探すことが出来ます。

$game_actors.item_holder( things(kind, id) )

　と記述すると、指定品を所持しているアクターのIDを配列で得ることができます。
　袋に指定品がある場合は、ID郡に加えて、0 を含んだ配列になります。

　どこにも指定の品がない場合、空の配列を返します。


--- ○指定の品をいくつ所持しているか？ --------------------------------------

　ひとりのアクターを指定して、
　そのアクターの、指定の品の所持数を取得するには以下を記述します。
　(actor_id の部分には任意のアクターIDを記入してください)

$game_actors[actor_id].carry_item_number( things(kind, id) )


　袋の中に、指定の品がいくつあるかを取得するには以下を記述します。

$game_party.carry_item_number( things(kind, id) )

　
　パーティー全体の、指定の品の所持数を取得するには以下を記述します。

$game_party.item_number( things(kind, id) )


　アクター全体の、指定の品の所持数を取得するには以下を記述します。

$game_actors.item_number( things(kind, id) )


　スタックアイテムの所持を、スタック数で知りたい場合は、
　アクター、袋、パーティー全体、アクター全体の順に以下のようになります。

$game_actors[actor_id].total_stack( things(kind, id) )
$game_party.total_stack( things(kind, id) )
$game_party.members_total_stack( things(kind, id) )
$game_actors.total_stack( things(kind, id) )


--- ○指定の所持品のインデックス取得 ----------------------------------------

  アクターと袋を対象に、
  指定の品がどこにあるか、ということをインデックスで取得できます。
  
  所持品個々は、このインデックスで管理されていますので
  あらゆる所持品の処理に、インデックスが必要になります。

  アクターの指定品インデックスを、配列で返すには以下を記述します。
　(actor_id の部分には任意のアクターIDを記入してください)

$game_actors[actor_id].carry_item_index( things(kind, id) )

　袋のアイテムの指定品インデックスを、配列で返すには以下を記述します。

$game_party.carry_item_index( things(kind, id) )



　取得したインデックスを使うメソッドはアクタークラスにいくつかあります。
　その中から、イベントに使えそうなものを、例として説明します。

　・インデックスのアイテムの消去

$game_actors[actor_id].remove_item_index(index)
$game_actors[actor_id].remove_item_index(index, true)       # 装備品も含む場合


　・インデックスのアイテムを変化

$game_actors[actor_id].change_item(index, kind, item_id)

　kind、id で変化後のアイテムを指定します。
　※ アイテムが装備中の場合、(装備可能ならば)装備状態を引き継ぎます。


--- ○装備品を含む場合 ------------------------------------------------------

　ここまでで説明した
　指定の品を所持しているか、誰が所持しているか、いくつ所持しているか
　の ( things(kind, id) ) の部分を
     ( things(kind, id), true ) とすることで、
  装備品を含んだ状態で、取得や判定をすることができます。

  (通常は装備品は省かれています)


== ●所持品の移動 ===========================================================  

  
--- ○所持品の入手 ----------------------------------------------------------
  
　イベントコマンド・アイテムの増減では
　増減可能なアクターを自動的にパーティー先頭から順に探すような処理をします。

　アクターを指定して、指定の品を入手させるには以下を記述します。
　(actor_id の部分には任意のアクターIDを記入してください)

actor_gain_item(actor_id, kind, id)

  アクターを指定して、指定の品を減少させるには以下を記述します。

actor_lose_item(actor_id, kind, id)

  上記では装備品の場合は減少させませんが、
  以下のように記述すると装備品であっても、指定の品を減少させます。

actor_lose_item(actor_id, kind, id, true)


--- ○所持品の装備 ----------------------------------------------------------

　イベントコマンド・装備の変更では、
　所持品入手→装備させたいアクターへ装備　がスムーズに行えるように、
　アクター自身が指定の品を所持していない場合は
　パーティー内から指定の品を探し出して受け取り後に装備するような動作をします。

　これに対し、装備命令のみを行い、アクター自身が指定の品を所持していないなら
　単に失敗（何も起こさない）で終わるのが以下のコマンドです。
　(actor_id の部分には任意のアクターIDを記入してください)

actor_equip_change(actor_id, kind, id)


　アクターの部位を指定して装備を破棄させることが出来ます。
　入手→装備と組み合わせれば、装備が変化したような演出ができます。

actor_equip_discard(actor_id, equip_type)

　equip_typeは装備タイプで、ここでは
　0:武器、1:盾or二刀流武器、2:身体防具、3:頭部防具、4:装飾品　で指定します。


--- ○所持品の確保 ----------------------------------------------------------

　アクターがパーティーを離脱する際など、
　プレイヤーが入手したアイテムを無駄にしない為の配慮が必要です。
　次のようなスクリプトで所持品を移動・退避させます。

　アクターの所持品を
　他のパーティー内のアクターに振り分けるには以下を記述します。

actor_items_distributes(actor_id)

　actor_idで指定した id のアクターの所持品が、
　パーティーの他メンバーへ振り分けられます。

actor_items_distributes(actor_id, true)

　とすれば、装備品もその装備を解除して他へ振り分けます。
　(通常は装備品は手放しません)

　振り分けは、受け取る側の他アクターの所持品がいっぱいになるまで行われます。
　つまり、受け取るアクターが持ちきれない場合もあるということです。
　以下はそれを事前に調べるメソッドで、
　持ちきれる場合は true 、持ちきれない場合は false を返すものです。

actor_items_distributes_test(actor_id)
actor_items_distributes_test(actor_id, true)       # 装備品も含む場合

　
　振り分けで所持品が残ってしまった際には、次のスクリプトを使います。
　アクターのアイテムを預かり所に送るメソッドです。

actor_items_entrusts(actor_id)　
actor_items_entrusts(actor_id, true)               # 装備品も含む場合

  預かり所に預けられない所持品が残ってしまう場合もあります。
  そういった場合は、別の機会（プレイヤーが所持品に余裕を作ってから）
  再度、振り分け処理を行うと良いと思います。
  
  　イベント例：
  　　預かり所などで「○○さんから預かっている物があります」などと表示し
  　　すでにパーティーから外れているアクターからの振り分け処理を行います。
  　　その際、先述したテストで振り分けが可能かテストを行い、
  　　持ちきれない場合は余裕を作って戻ってくるよう説明します。
  

  
  アクターからアクターへ所持品をまるまるコピーするメソッドも用意しています。
  
actor_items_copy(actor_id, other_actor_id)
actor_items_copy(actor_id, other_actor_id, true)    # 装備品も含む場合
  
  actor_id のidアクターから、
　other_actor_id のidアクターへ所持品をコピーします。
  受け取る側であるother_actor_id のidアクターの所持品は破棄されます。

  　　受け取りにダミーアクターなどを使って、
  　　一時的にアイテムを退避させる目的でコピーは使えます。
  　　主人公の回想シーンや、捕虜になり所持品を失うシーンなどに。
  
  所持品をすべて消去する場合は以下の記述を行います。
  
actor_items_clear(actor_id)
actor_items_clear(actor_id, true)                   # 装備品も含む場合
  

=end