2018-01-28

本マニュアルは旧版です。新しいマニュアルは以下を参照してください。
sorcerian.hateblo.jp

開発者マニュアル目次（http://d.hatena.ne.jp/sorcerian/20171221）

SGML（Sorcerian Gamebook Markup Language）仕様

ソーサリアンTextのシナリオデータは、SGMLと呼ばれるXMLベースのマークアップ言語で記述します。以下は、SGMLで利用できる要素／属性の一覧です。それぞれの詳しい用法は、サンプルシナリオも合わせて参照してください。

<scenario>　ルート要素（シナリオ全体を括る）
- @title　シナリオタイトル
- @author　作者名
- @xmlns:xsi、@xsi:noNamespaceSchemaLocation　システム情報*1
- <init>　シナリオ初期化情報全体を括る
  - <constraint>　シナリオ起動時に生成される種族／性別／年齢（すべて許容する場合は指定しない）
    - @race　種族（FIGHTER、WIZARD、DWARF、ELF。カンマ区切りで複数列記可）
    - @sex　性別（MALE、FEMALE。複数列記は不可）
    - @age　年齢（YOUNG、ADULT、OLD。カンマ区切りで複数列記可）
  - <bgm>　シナリオに適用するbgm（すべて既定ならば省略可）
    - @main　メインテーマ（既定はmain。詳細は下記）
    - @happy　ハッピーエンド（既定はhappy。詳細は下記）
    - @bad　バッドエンド（既定はbad。詳細は下記）
  - <intro>　シナリオの紹介情報
    - description　紹介文（シナリオ共通でツイートボタンに反映される）
- <items>　アイテム情報全体を括る
  - <item>　個々のアイテム（複数列挙可）
    - @id　アイテムコード
    - @name　アイテムの名前
    - text　アイテムの説明（15文字程度）
- <flags>　フラグ情報全体を括る
  - <flag>　個々のフラグ情報（複数列挙可）
    - @id　フラグコード（接頭辞「f」。シナリオ内で一意であること）
    - text　フラグの表示名（15文字程度）。先頭が「*」で始まる場合には、ステータス画面で表示されない隠しフラグとなる
- <enemies>　敵情報全体を括る
  - <enemy>　敵／罠の情報
    - @id　敵コード（接頭辞「m」。シナリオ内で一意であること）
    - @name　敵／罠の名前（10文字程度）
    - @element　属性。earth（地）／fire（火）／water（水）／wind（風）／spirit（霊）のいずれか（無指定の場合は無属性と見なす）
    - @attack　攻撃の種類。physics（物理）／magic（魔法）／poison（毒）／frozen（凍結）／stone（石化）／curse（呪い）／forget（忘却）のいずれか1つ*2
    - @func　ダメージ式（後述）
    - @drop　ドロップアイテム（「mon/3」で「月×3」*3、「free1/50/50Gold」で「50Gold」*4）。無指定の場合は属性からドロップアイテムを確定
    - text　モンスターの説明（50文字程度）
- <results>　実績情報全体を括る
  - <result>　個々の実績情報（複数列挙可）
    - @id　実績コード（接頭辞「r」。シナリオ内で一意であること）
    - @name　実績名（ex. ガジガジネズミ）
    - @level　難易度（1～5）
    - text　実績の成立条件（ex. 隧道でネズミに食い殺された）
- <licence>　ライセンス情報
  - <work>　作品情報（複数列挙可）
    - @name　曲名（bgmの場合）、利用場所（pictureの場合。街、酒場など）
    - @category　分類（bgm：音楽、picture：画像）
    - @creator　作者 or サイト名
    - @url　参照先
- <scene> シーン情報（複数列挙可）
  - @id シーン番号（リンク時にも利用する番号なので一意で。スタートは0固定、プロローグであること）
  - @items　そのシーン移動時に入手できるアイテム（複数はカンマ区切り。「-i～」でアイテム喪失）
  - @flags　　そのシーン移動時に立つフラグ（複数はカンマ区切り。「-f～」でフラグ破棄。但し、削除できるのは隠しフラグのみ）
  - @enemies　敵情報（複数はカンマ区切り*5）
  - @stars　そのシーン移動時に加算／減算する星（月～太陽の順で「9,9,9,9,9,9,9」のカンマ形式。途中省略は不可。負数指定も可*6）。特殊形式として「divN」ですべての星を1/Nにもできる（小数点以下切捨）
  - @hp　そのシーン移動時に加算／減算するhpの量（負数指定も可。また、「-10..-1」で範囲内ランダム、「full」で上限）
  - @mp　そのシーン移動時に加算／減算するmpの量（負数指定も可。また、「-10..-1」で範囲内ランダム、「full」で上限）
  - @free1　そのシーン移動時に加算／減算するfree1の量（負数指定も可）
  - @free2　そのシーン移動時に加算／減算するfree2の量（負数指定も可）
  - @free3　そのシーン移動時に加算／減算するfree3の量（負数指定も可）
  - @result　そのシーン移動時に取得できる実績
  - @bgm　シーン移動時にBGMを切替（詳細は下記）
  - @se　シーン移動時に再生する効果音（se.mp3であれば、「se」と指定）
  - @allowMove　番号指定による移動を許可するか（値はtrue固定）2018/05削除
  - @end　エンディングシーンか（happy：ハッピーエンド、bad：バッドエンド）
  - text　シナリオ本文（Markdown形式。以下詳細）

シナリオデータのテンプレート（骨組み）は、/stext/common/template/scenario.xmlとして用意しています。/templateフォルダーごとコピーしてご利用ください。

@idについて

すべて半角英数字
アイテムコード／フラグコード／敵コードはシナリオ内で一意であること
アイテムコードは「i～」、フラグコードは「f～」、敵コードは「m～」、実績コードは「r～」で始まること
シナリオコードはシステム全体で一意であること（基本、Upload時に決定）

<bgm>要素、bgm属性について

拡張子「.mp3」を除いたベース名で指定します（例えば、battle01.mp3ではなく、battle01）
頭に「@」付きでシステム標準のBGMを意味します
- 利用できる.mp3ファイルの名前については、STextページよりUtility 01を確認してください（たとえば@field01、@castle01など）。
- 標準BGMについては、シナリオフォルダーに.mp3ファイルを格納する必要はありません
頭に「@」のないファイル名は、シナリオフォルダー配下の/bgmフォルダーを見に行きます。対応する.mp3ファイルを準備してください。
end属性のあるシーンでbgm属性を指定した場合には、bgm属性が優先されます。

■注意■
旧仕様では、シナリオフォルダーの配下に、bgm_happy.mp3、bgm_bad.mp3、bgm_boss.mp3のような名前で格納していましたが、今後は/bgmフォルダー配下にhappy.mp3、bad.mp3、boss.mp3となります。

enemy要素のfunc属性について

（1）attack属性がphysics／magicの場合
ダメージ式は「nL+nR+n-nSTR-nINT-nDEX-nKRM-nFREE1-nFREE2-nFREE3」で統一（Lは左のサイコロ、Rは右のサイコロ）。ただし、以下の制約があります。

nは任意の数値
符号（̟プラスマイナス）は差し替え可能
すべての項は省略可能＆順番も入れ替え可能
カッコは利用できない

（2）attack属性が状態異常の場合
回避条件を「[exp]>[exp]」の形式で指定する（[exp]はダメージ式と同様の形式）。
回避条件を満たさなかった場合にだけ、指定の状態異常が付与されます。

■注意■
以前の仕様では、WIZARD（魔法使いの時に回避）のような記述を許容していましたが、利用されていないようだったので、廃止しています。今後、ご要望次第でサポートを検討します。

（1）（2）いずれの場合も、カンマ区切りで複数指定も可（その場合はランダムに式を選択します）
ダメージ式／回避条件のステータスへの反映（自動計算）は、func属性の頭に「*」を付与することで無効化できます（自動化ができないシナリオでは「*」を付与してください）。

フォルダー構造

シナリオファイルは、以下のようなフォルダー構造で配置してください。

/シナリオコード　シナリオルート
- scenario.xml　シナリオデータ
- /bgm　BGM
  - xxxxx.mp3　xxxxxはアルファベット小文字と数字（サイズは1mb程度までを推奨）
  - /se　効果音
    - xxxxx.mp3　xxxxxはアルファベット小文字と数字（サイズは30kb程度までを推奨）
- /capture　挿絵
  - xxxxx.png　xxxxxはアルファベット小文字と数字（シーンについてひとつまでを推奨）

ローカル環境で、開発したシナリオを実行する場合には、このフォルダーを/stextフォルダーに配置します（現在はサンプルとして/scepterフォルダーをはじめ、いくつかのシナリオフォルダーが置いてあります）。

■Note■
シナリオを新規に投稿する場合は、トップフォルダーを圧縮して.zipファイルとしてお送りください。投稿方法については、STextサイト（http://www.web-deli.com/sorcerian/next/stext.aspx）を参照してください。

注意事項

ファイル名に「_」などの記号は利用できない
- 原則として、ファイル名はアルファベット小文字＋数字で統一してください
挿絵の枚数は制限しない
- 1シーンに複数のイラストがあっても構わないし、複数シーンで同一のイラストを共有しても構わない
- ただし、読みやすさの観点から、1シーン複数イラストは避けることを推奨
カンマ区切りのコード前後には空白は入れない
- 問題なく動くものもありますが、現時点ではサポートしていません。
システムコードはシステム全体で一意であること
- 公開時に採番するので、開発時は「test」で固定
- ローカル環境でシナリオの動作を確認する場合には、トップフォルダーの名前が「test」であることを確認した上で、/stextフォルダー直下にコピーしてください。あとは、トップページの選択ボックスから［テストシナリオ］を選択することで、シナリオを起動できます。

Markdown形式

ブログなどに利用される簡易なテキストフォーマットです。
画像や表組み、リンク、箇条書きリストなどが可能です。
詳しくは、以下のようなページを参考にしてください。

http://kojika17.com/2013/01/starting-markdown.html
＃ただし、一部の機能が非対応の可能性もあるので、ご了承くださいm(_ _)m

SGML固有のルール（リンクボタン）

SGMLでは、以下のように移動ボタンを表します。

[ボタンキャプション](リンク先番号)

[冒険に出発する](1)

フラグ／アイテムなどの有無によって移動ボタンの表示／非表示を制御できます。

（1）フラグがある／ない場合のみ表示

[ボタンキャプション](リンク先番号 "フラグコード")
[ボタンキャプション](リンク先番号 "-フラグコード")

[フラグ確認用1](12 "f1")
[フラグなし確認用1](12 "-f1")

（2）アイテムがある／ない場合のみ表示

[ボタンキャプション](リンク先番号 "アイテムコード")
[ボタンキャプション](リンク先番号 "-アイテムコード")

[アイテム確認用1](12 "i1")
[アイテムなし確認用1](12 "-i1")

（3）魔法を利用できる／できない場合のみ表示

[ボタンキャプション](リンク先番号 "m魔法名")
[ボタンキャプション](リンク先番号 "-m魔法名")

[魔法確認用（HEAL）](12 "mHEAL")
[魔法なし確認用（HEAL）](12 "-mHEAL")

■Note■
魔法ボタンでの移動時には、自動的に対応する星が減算されます。

（4）ステータスが指定値を上回っている／下回っている場合のみ表示

[ボタンキャプション](リンク先番号 "-o［ステータス種別］［値］［+/-］")

[STRが5より大きい場合のみ表示](12 "oSTR5+")
[HPが50未満の場合のみ表示](12 "oHP50-")

ステータス種別にはSTR、INT、DEX、KRM、HP、MP、FreeI、FreeII、FreeIIIを指定可能

（5）キャラの基本情報が合致している／していない場合のみ表示

[ボタンキャプション](リンク先番号 "x情報")
[ボタンキャプション](リンク先番号 "-x情報")

[種族がFIGHTER](41 "xFIGHTER")
[種族がFIGHTERでない](41 "-xFIGHTER")
[性別がMALE](41 "xMALE")
[年齢がOLD](41 "xOLD")
[状態異常がFROZEN](41 "xFROZEN")
[職業がのうふ](41 "xのうふ")

情報には、以下のものを指定可能

種族（FIGHTER／WIZARD／DWARF／ELF）
性別（MALE／FEMALE）
年齢帯（YOUNG／ADULT／OLD）
状態異常（POINSON／FROZEN／STONE／CURSE／FORGET）
職業（のうふ／こじきなど。ひらがな表記）

（6）個々の星を指定数以上、所持している／いない場合のみ表示

[ボタンキャプション](リンク先番号 "s月:...:太陽")
[ボタンキャプション](リンク先番号 "-s月:...:太陽")

[星が各7以上](2 "s7:7:7:7:7:7:7")
[星の各7以上ない](2 "-s7:7:7:7:7:7:7")

（7）星の所持総数が指定数以上である／ない場合のみ表示

[ボタンキャプション](リンク先番号 "s総数")
[ボタンキャプション](リンク先番号 "-s総数")

[星の総数49以上](2 "s49")
[星の総数49未満](2 "-s49")

（8）実績がある／ない場合のみ表示

[ボタンキャプション](リンク先番号 "実績コード:シナリオコード")
[ボタンキャプション](リンク先番号 "-実績コード:シナリオコード")

[実績確認用（r01:scepter）](12 "r01:scepter")
[実績なし確認用（r15:tempest）](12 "-r15:tempest")

（9）指定された条件をすべて満たしている場合のみ表示（カンマ区切り）

利用できる条件は以下の通り（異種混在も可）

フラグ／アイテムを所有している
魔法を利用できる
実績を保持している
ステータス条件を満たしている
基本情報が合致している

[ボタンキャプション](リンク先番号 "フラグ／アイテムコード／m魔法／o条件...")

[マルチフラグ確認用1](12 "f1,f2,f3")
[マルチアイテム確認用1](12 "i1,i2")
[マルチ魔法確認用1](12 "mHEAL,mCURE")
[マルチステータス確認用1](12 "oSTR5+,oHP50-")
[マルチ実績確認用1](51 "r01:scepter,r02:tempest")
[混合例確認用1](51 "r01:scepter,mHEAL")

（10）指定された条件のいずれかを満たしていない場合のみ表示

利用できる条件は（9）に準ずる（異種混在も可）

[ボタンキャプション](リンク先番号 "-フラグ／アイテムコード／m魔法／o条件,...")

[マルチフラグなし確認用1](12 "-f1,f2,f3")
[マルチアイテムなし確認用1](12 "-i1,f2,i3")
[マルチ魔法なし確認用1](12 "-mHEAL,mCURE")
[マルチステータスなし確認用1](12 "-oSTR5+,oHP50-")
[マルチ実績なし確認用1](51 "-r01:scepter,r02:tempest")
[混合例確認用1](51 "-r01:scepter,oSTR5+")

（11）シーン番号を入力しての移動を可能にする場合

以下のように、リンク先をX、キャプションに移動可能なシーン番号をカンマ区切りで列挙したリンクを用意します（任意移動リンクはシーンにひとつしか設置できません）。

[10,11,12](X)

（12）入力文字列を判定して正否によって分岐

以下のように、リンク先をQ、キャプションを「正答,正しい時の移動先,間違った場合の移動先」としたリンクを用意します（文字列入力リンクはシーンにひとつしか設置できません）。

[グーラン,11,12](Q)

上の例では、「グーラン」と入力した場合には11へ、さもなければ12へ移動します。

（13）ランダムな移動を可能にする場合

以下のようにリンク先番号をカンマ区切りで列挙することもできます。この場合、リンク先はその時どきにランダムで決まります。

[ランダムリンク](1,2,3)

SGML固有のルール（テキスト加工）

SGMLでは、Markdownを拡張して、カラーリングや式の埋め込みにも対応しています。

式埋め込み

${...}の形式で、テキストの任意の箇所に式の埋め込みが可能です。
利用可能な式は、以下の通りです。

${title} … 称号
${name} … キャラクターの名前
${race?人間:魔法使い:ドワーフ:エルフ} … 種族に応じて単語を置き換え
${sex?男:女} … 性別に応じて単語を置き換え
${state?正常:毒:凍結:石化:忘却} … 状態異常に応じて単語を置き換え
${age?若者:中年:老人} … 年齢帯に応じて単語を置き換え
${rand?1:20} … 指定の値範囲で乱数を生成
${msg?こんにちは:おはよう:こんばんは} … 指定のメッセージをランダムに選択

「?」以降は、「:」区切りで表示すべき任意の単語を指定できます。

条件分岐

${if xxx}～${/if}の形式で、テキスト内に条件付きで表示するテキストを指定できます。xxxにはフラグid（f01など）、アイテムid（i01など）のいずれかを指定できます。

${if f04}
フラグ04が立っている時にだけ表示されます。
${/if}

現時点では、指定できるのは単一のコードだけで、複合条件は未サポートです。

ルビ指定

${元の文字列|ルビ}の形式で、ルビの指定も可能です。

俺は${銀狼|silver wolf}だ！

テキストのカラーリング

%blue%～%/%でテキストを囲むことで、任意のテキストにカラーリングも可能です。

みんな、%blue%ソーサリアン%/%だ！

ただし、現時点では以下の制約があります。

現在利用できるカラーは、blue、red、purple、whiteのみです*7。
カラーリングしたテキストの前後には、半角スペースが入ります。

ツイートボタンへの反映

${tweet}～${/tweet}で、任意のテキストを括ることで、その内容を［ツイート］ボタンに反映できます。以下は制約事項です。

${tweet}配下では、Markdownによる修飾はできません。
${tweet}はひとつのシーンでひとつしか利用できません（複数は上書き）。
指定されていないシーンでは、init－intro要素での設定値が利用されます。
- 指定したシーンでは、intro要素での設定値は上書きされます。

■Note■独自サイトでSTextを運用する方向け
ツイートボタン機能を利用するには、「class="socialbtn twitter"」「class="socialbtn twitter_custom"」である要素をページの任意の箇所に配置してください。［ツイート］ボタンのプレイスホルダー（表示領域）となります。
※公式のSTextサイトでシナリオ公開する方には関係ありません。

セーブデータ

セーブデータは以下の2種類。
いずれもJSON形式でWeb Storageに保存され、次回起動時に復帰できます。

シナリオを跨いだ「グローバルセーブデータ」
シナリオ単位に設置される「ローカルセーブデータ」

グローバルセーブデータ

初回のシナリオ生成時に生成され、複数のシナリオ間で共有される
キーは固定で「sorcerian_text」

以下はセーブデータの構造。

items　シナリオ終了時に得られるアイテム（シナリオ共通で累積される）
results　実績情報（「シナリオid: 実績リスト」の形式）
panel　コントロールパネルは表示状態か
bgm　BGMを再生するか

ローカルセーブデータ

個々のシナリオ開始時に生成され、シナリオ固有の情報を管理する
シナリオ開始時にキャラは自動生成（「ソーサリアンになったったー」のイメージ）
- 基本ステータスは種族／性別で決定（別表の基準値をもとにランダム決定）
キーは「シナリオコード」