內建函式
========

.. _Script_inbuild_page:

腳本自定義相較其他腳本製作紹更為複雜，但卻可以幫助玩家使用上更為彈性且設計獨有的邏輯判斷
於本頁中，我們將為您介紹 :ref:`變數型別<Script_var>` 、 :ref:`基本型態<Script_type>` 、:ref:`內建運算子<Operators>` 以及 :ref:`陳述式<Statements>` 的使用方法與規則。



.. _Script_var:

變數型別
----------
| Blackey Script是一個動態強型別(Dynamically, Strongly typed)的語法
| 指定型別的方式跟Python非常接近


    .. code-block :: 

        // Assign x as an integer
        x = 1;
        print(x);
        
        // Assign x as a character
        x = “Hello”;
        print(x);

| Console: 
| ``1.000000`` 
| ``Hello``           

.. note::
        
    | 動態型別表示在運行腳本期間動態地進行型別的解析，與之相對的是靜態型別。
    | 如C/C++，你需要在宣告變數時指定它的型態。
    | 強型別則表示 **不允許** 錯誤型別的參數進行運算，例如將數值與字串進行相加，舉例如下：

    | x = 1 + “hello”;


.. _Script_type:

基本型態
---------
Blackey Script的基本資料類型只有浮點類型以及字串類型，
另外有兩個衍生類型是座標點(Position)以及區域(Region)。
目前支援的型別如下表所示：

 =========  ====================  ==========================================
  型別       表示法                 意含
 =========  ====================  ==========================================
 Number      x = 1;    	          指定 x 為 1 的數值
 String      x = “Hello”;         指定x為”Hello”的字串（雙引號不可省略）
 Position    x = pos(0.1, 0.3);   | 指定相對座標點（x,y）    
                                  | 原型為：position(x-axis value, y-axis value)
                                  | 螢幕的左上角是起點(0, 0)
                                  | 第一個 0.1 表示畫面左邊數來的10%
                                  | 第二個 0.3 表示畫面上面數來的30%
 =========  ====================  ==========================================

.. important::
    請注意Blackey Script目前僅支援上述的型別，
    部份常用如：指標(pointer)、陣列(array)、結構(struct)、類別(class)等，尚不支援！    


.. _Operators:

內建運算子
----------

搭配不同的條件判斷，寫出更複雜的腳本
欲進行指令自定義編撰，則須熟知各運算子代表意含及優先順序
並由左至右進行計算

- 數學計算 

 =======  ========  =======================
 功能       運算子      範例
 =======  ========  =======================
 乘法       ＊          x = 1 * 2;
 除法         /          x = 6 / 2;
 餘數         %          x = 5 % 3;
 加法         ＋         x = 1 + 2;
 減法       \ *-*\         x = 1 – 2;
 =======  ========  =======================

- 數值比較 

 ===========  ========  =======================
 功能          運算子      範例
 ===========  ========  =======================
 相等            ==        x == 1
 不等於	         !=        x != 1
 大於           >          x > 1
 小於            <         x < 1
 大於或等於       >=          x >= 1
 小於或等於       <=          x <= 1
 ===========  ========  =======================

- 邏輯判斷 

 =========  ========  =======================
 功能         運算子      範例
 =========  ========  =======================
 邏輯AND        &&        x && y
 邏輯OR	        ||         x || y
 =========  ========  =======================

- 其他 

 ============  ========  ==========================  
 功能            運算子      範例                           
 ============  ========  ==========================  
 指派            =           x = 1;             
 逗號	         ,         x = 1, y = 2; print(x, y);
 函式呼叫         ()        print(x);
 一元否定運算    \ *-*\           x = -1; y = 1 * -3;
 ============  ========  ==========================  


.. note::
        
    | 由於運算子順序大多與C語言相近，依照優先度將運算子進行排序並計算出下列答案，舉例如下：
    | x = 5;
    | y = z = 1 * -2 + 3 * 4 – -x;
    |

    | 解析：
    | 由右至左進行計算，一元否定運算式相對於其他運算子還要高，因此先行計算
    | 再來是乘法（乘除法又較加法減法來得高），最後才是指定符號
    | 所得：y=z=15


.. _Statements:

陳述式
--------
此方法用於控制變數要如何操作、怎麼進行操作的程式碼，Blackey Scripts的陳述式同樣借鑒了C++的語法進行撰寫，一般而言，程式碼的多數比例為運算陳述式，運算陳述式將會由上到下依序執行，執行過程遇到其他陳述式時則可能進行跳轉。

下列將列出四種陳述式及範例

運算陳述式 Expression statement
+++++++++++++++++++++++++++++++++
 運算陳述式會依序執行，最常見的運算陳述式如指派/呼叫函式等

.. code-block :: 

    x = 1;
    y = 1 * 2;
    print(y);


選擇陳述式 – Selection statement
+++++++++++++++++++++++++++++++++
目前Blackey Script在選擇陳述式只支援 **if-else** ，此陳述式使用運算陳述式做為條件來控制分支，當if運算式得到為非零值時，就會跳轉進入if區塊中，而不執行其他區塊。
如果運算的值為零，則會略過if區塊，跳轉進入else區塊執行 (如果有else區塊的話)。

 - 範例

 .. code-block :: 

    x = 1;
    y = 2;
    if (x < y) {

        print(“x 小於 y”);

    } else {

        print(“x 大於等於 y”);

    }

 Console: ``x 小於 y`` 

.. tip::
 請參考下方3式選擇陳述式規則


 - **case1 條件式陳述**

 .. code-block :: 

    // If the expression is non-zero (true), run the if-statement.
    if ( expression ) {

        statement1;
        …

    }
       

 - **case2 條件式陳述控制執行區塊**

 .. code-block :: 
        

    // If the expression is non-zero (true), run the statement1，instead of the statement2.

    if ( expression ) {

        statement1;
        …

   

    } else {
 
        statement2;
        …

    }


 - **case3 條件式陳述控制執行區塊**

 .. code-block :: 
    
    // If the expression is non-zero (true), run the statement1.

    if ( expression ) {

        statement1;
        …
    }

    
    // If the expression2 is non-zero (true)，run the statement2.

    else if (expression2) {
            
        statement2;
            …
        }

    // If both the expression1 and expression2 are zero (false), run the statement3.

    else {
 
        statement3;
        …

        }


疊代陳述式 – Iterator statement
++++++++++++++++++++++++++++++++
疊代陳述式會使指定區塊依據某個條件來決定執行次數，次數可以為0到多次，一般我們將疊代陳述式稱作 **迴圈** ,在疊代陳述式終止條件前，如遇到 :ref:`跳躍陳述式<JumpStatement>` 也可能提早中止迴圈。
目前Blackey Script在疊代陳述式只支援 **while**

 - 範例
    
 .. code-block :: 

    ...

    x = 0;
    while (x < 5) {     # while(expression)

        print(x);
        x = x + 1;

    }

 Console: ``0, 1, 2, 3, 4`` 


.. _JumpStatement:

跳躍陳述式 – Jump statement
++++++++++++++++++++++++++++
跳躍陳述式會從目前的區塊進行跳轉至其他的區塊中執行。

 - 跳躍陳述式語法 

 ====================  =========================================  
 語法                       功能                           
 ====================  =========================================  
  break;                 跳過該區塊剩餘的語句，離開當前的迴圈             
  continue;	             跳過該區塊剩餘的語句，開始下一次的迴圈循環
  return[expression];    跳過該區塊剩餘的語句，回傳陳述表達式的運算結果。
 ====================  =========================================  

 .. _breakStatement:

 - break 用法

 .. code-block :: 

    ...

    x = 0;
    while (x < 100) {

        print(x);
        x = x + 1;
        if (x > 5) {

    print(“break out”);
    break;

        }

    }
    print(“done”);

 Console: ``0, 1, 2, 3, 4, 5, “break out”, “done”`` 


 - continue 用法

 .. code-block :: 

    ...

    x = 0;
    while (x < 100) {

        x = x + 1;
        if (x > 5) {

            continue;

        }
        print(x);

    }
    print(“done”);

 Console: ``1, 2, 3, 4, 5, “done”`` 



 - return 用法

 .. code-block ::

    ...

    x = 0;
    while (x < 100) {
            
        print(x);
        x = x + 1;
        if (x > 5) {

            print(“break out”);
            return 0;

        }

    }
    print(“done”);

 Console: ``0, 1, 2, 3, 4, 5, “break out”`` 

 .. tip::
    跟跳躍陳述式的 :ref:`break <breakStatement>` 範例不同，這邊不會印出”done”,程式運行至return 0後，便跳出此程式區塊。

 - exit 用法

 exit陳述式的使用方式通常用於自定義函數中，在執行到exit的時候就終止整個腳本的運行。帶入非0值時，會在日誌視窗印出日誌，方便確認錯誤的發生點。

 .. code-block :: 

    ...

    def quitCheck(val) {

        if (val == 3) {

            exit(1);

        }

    }
        
    x = 0;
    while (x < 100) {
            
        x = x + 1;
        quitCheck(x);
        print(x);        

    }

| Console: ``1, 2, 3, 4`` 
| exit(1) Console: [Line: 13] exit error code 1.000000
    
|
|
|

:ref:`進入腳本編撰<腳本編撰>` or
:ref:`回到頂部<內建函式>`