Skip to content

Commit

Permalink
update docs. [skip CI]
Browse files Browse the repository at this point in the history
  • Loading branch information
pigpigyyy committed Jan 24, 2024
1 parent bc62625 commit 0b9e547
Show file tree
Hide file tree
Showing 13 changed files with 492 additions and 196 deletions.
20 changes: 12 additions & 8 deletions Site/docs/tutorial/Using Dora Xml/dora-xml-ui-1.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,15 @@ import "@site/src/languages/highlight";
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Using Dora Xml for UI Development I
# Using Dora XML for UI Development I

Dora SSR provides a functionality called Dora Xml, which helps separate the graphical presentation and logical processing code. The core functionality of Dora Xml is to write code for graphical presentation and interaction, especially code focused on user display in game UI interfaces, using an XML markup language, similar to HTML in web pages. Creating UI components, setting layout dimensions and appearance colors, creating interactive animations, and UI animations triggered by events can all be organized and written in the Dora Xml language. Dora Xml mostly complies with the XML specification, but with some modifications and additions, including many predefined tags and the ability to create custom tags.
Dora SSR provides a functionality called Dora XML, which helps separate the graphical presentation and logical processing code. The core functionality of Dora XML is to write code for graphical presentation and interaction, especially code focused on user display in game UI interfaces, using an XML markup language, similar to HTML in web pages. Creating UI components, setting layout dimensions and appearance colors, creating interactive animations, and UI animations triggered by events can all be organized and written in the Dora XML language. Dora XML mostly complies with the XML specification, but with some modifications and additions, including many predefined tags and the ability to create custom tags.

To write Dora Xml, you can create and edit code files in the web IDE provided by Dora SSR to benefit from features such as syntax highlighting, code completion, and error checking, which make the writing process much more easier. Now let's see how to use Dora Xml to write a custom button component.
:::tip Use Dora TSX instead
Currently Dora SSR also provides a solution to use TSX to write game scenes or UI interfaces. It can provide better code editor auxiliary functions through Typescript language and offers more detailed syntax static checking. However, using The TSX solution will slightly decrease performance. If you do not encounter performance problems, it is recommended to use Dora TSX instead of Dora XML.
:::

To write Dora XML, you can create and edit code files in the web IDE provided by Dora SSR to benefit from features such as syntax highlighting, code completion, and error checking, which make the writing process much more easier. Now let's see how to use Dora XML to write a custom button component.

First, let's design our button:

Expand All @@ -16,7 +20,7 @@ First, let's design our button:
* The appearance of the button should change when a click event is triggered.
* As an independent control, it should be reusable in multiple places and support adjusting displays with different parameters.

Now we can start our Dora Xml coding.
Now we can start our Dora XML coding.

### 1. Creating a Clickable Area

Expand Down Expand Up @@ -131,7 +135,7 @@ We use the `<Import>` tag to import the XML module. The `Module` attribute of Im

The Import module can have additional attributes. Apart from the special-purpose built-in attributes Name and Ref (Ref="True" allows accessing the module object through the root node variable, and Name is used for subsequent code references), any other attributes set will be passed as lowercase parameter variables into the module internally. So be sure to fill in the required parameter variables in the module.

This way, our custom button is complete. Loading and running a Dora Xml file is straightforward; you can directly load it like a regular Lua file. For example:
This way, our custom button is complete. Loading and running a Dora XML file is straightforward; you can directly load it like a regular Lua file. For example:

```lua
local Director = require("Director")
Expand Down Expand Up @@ -167,11 +171,11 @@ return function()
end
```

In fact, Dora Xml is compiled into Lua code for execution. The above code is the result of compiling MainScene.xml. However, writing Lua code logic using XML tags provides a clearer code structure and improves the maintainability of the program.
In fact, Dora XML is compiled into Lua code for execution. The above code is the result of compiling MainScene.xml. However, writing Lua code logic using XML tags provides a clearer code structure and improves the maintainability of the program.

### 7. Creating a Button Template

If we want to create buttons with different appearances but similar functionality, we can create a reusable template for certain fixed button functionalities. In Dora Xml, we can modify the previously written button into such a template.
If we want to create buttons with different appearances but similar functionality, we can create a reusable template for certain fixed button functionalities. In Dora XML, we can modify the previously written button into such a template.

```xml title="ButtonBase.xml"
<!-- params: X, Y, Width, Height, Text, FontSize -->
Expand Down Expand Up @@ -201,7 +205,7 @@ local buttonBase = ButtonBase()
print(buttonBase.face) -- This will give you access to the face node
```

Next, we can use this template in Dora Xml:
Next, we can use this template in Dora XML:

```xml title="SpriteButton.xml"
<!-- params: X, Y, Text -->
Expand Down
10 changes: 5 additions & 5 deletions Site/docs/tutorial/Using Dora Xml/dora-xml-ui-2.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,9 @@ import "@site/src/languages/highlight";
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Using Dora Xml for UI Development II
# Using Dora XML for UI Development II

After defining the graphical UI using Dora Xml, the next problem to solve is how to add handling logic for UI interactions. We can use the class mechanism of Dora SSR to write a new class that inherits from the Xml UI component and contains the interface logic for the UI. For example, we have a button Xml component.
After defining the graphical UI using Dora XML, the next problem to solve is how to add handling logic for UI interactions. We can use the class mechanism of Dora SSR to write a new class that inherits from the XML UI component and contains the interface logic for the UI. For example, we have a button XML component.

```xml title="ButtonView.xml"
<!-- params: X, Y, Radius, Text, FontSize -->
Expand Down Expand Up @@ -75,7 +75,7 @@ The business logic we added to the button mainly includes a feature to count the

```xml title="MainSceneView.xml"
<Node>
<Import Module="Button"/><!-- Import the Lua module directly in Xml -->
<Import Module="Button"/><!-- Import the Lua module directly in XML -->

<Menu X="100" Y="100" Width="100" Height="100">
<Button X="25" Y="25" Radius="50" Text="Click"
Expand Down Expand Up @@ -112,11 +112,11 @@ local MainScene = require("MainScene")
Director.entry:addChild(MainScene())
```

This way, the organization of our program logic for UI development is more complete. We use Dora Xml to manage the appearance of the UI, and then write the UI logic in Lua classes. Now the appearance definition of UI components and the code for business logic can be developed and maintained in separate files.
This way, the organization of our program logic for UI development is more complete. We use Dora XML to manage the appearance of the UI, and then write the UI logic in Lua classes. Now the appearance definition of UI components and the code for business logic can be developed and maintained in separate files.

## Writing UI Logic with Yuescript

With Dora Xml simplifying the UI code, we can further introduce a new language called Yuescript for development. Yuescript is a language that compiles into Lua and can seamlessly integrate with Lua. Its main feature is concise and easy-to-maintain code. Let's see how to use Yuescript together with Dora Xml to write business logic. The code from the previous section can be written in Yuescript as follows:
With Dora XML simplifying the UI code, we can further introduce a new language called Yuescript for development. Yuescript is a language that compiles into Lua and can seamlessly integrate with Lua. Its main feature is concise and easy-to-maintain code. Let's see how to use Yuescript together with Dora XML to write business logic. The code from the previous section can be written in Yuescript as follows:

```yue title="Button.yue"
_ENV = Dora!
Expand Down
6 changes: 4 additions & 2 deletions Site/docs/tutorial/dev-configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -95,8 +95,10 @@ git clone https://github.com/ippclub/Dora-SSR.git
2. Install the latest version of **Node.js**.
3. Initialize the project and enter the Dora Dora editor development mode.
```sh
cd Tools/YarnEditor && yarn && yarn build && rm -rf ../dora-dora/public/yarn-editor && mv dist ../dora-dora/public/yarn-editor && cd ../..
cd Tools/dora-dora
cd Tools/YarnEditor && yarn && yarn build
rm -rf ../dora-dora/public/yarn-editor
mv dist ../dora-dora/public/yarn-editor
cd ../../Tools/dora-dora
yarn
yarn start
```
81 changes: 56 additions & 25 deletions Site/docs/tutorial/quick-start.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -30,28 +30,57 @@ import TabItem from '@theme/TabItem';
- In the browser, open the right-click menu of the game resource tree on the left side of the Dora Dora editor.
- Click the `New` menu item, select "New Folder", and name it `Hello`.
2. Step Two: Write the game code
- Create a new game entry code file in the project folder, select the Yuescript language (or Teal, Lua), and name it `init`.
- Create a new game entry code file in the project folder, select the Yuescript language (or Teal, Lua, Typescript), and name it `init`.
- Write the code:

<Tabs>
<TabItem value="tsx" label="TSX">

```tsx title="Hello/init.tsx"
// @preview-file on
import { React, toNode, useRef } from 'dora-x';
import { Ease, Move, Sprite } from 'dora';

const sprite = useRef<Sprite.Type>();

// create the root node of the game scene tree
// and a sprite as a child node
toNode(
<node onTapBegan={(touch) => {
const sp = sprite.current;
if (sp) {
sp.perform(Move(
1, // duration in seconds
sp.position, // start position
touch.location, // end position
Ease.OutBack // easing function
));
}
}}>
<sprite ref={sprite} file='Image/logo.png'/>
</node>
);
```

</TabItem>
<TabItem value="yue" label="Yuescript">

```yue title="Hello/init.yue"
-- Import modules
-- import modules
_ENV = Dora!
-- Create a sprite
-- create a sprite
sprite = Sprite "Image/logo.png"
-- Create the root node of the game scene tree
-- create the root node of the game scene tree
with Node!
-- Mount the sprite to the root node
-- mount the sprite to the root node
\addChild sprite
-- Receive and process click events to move the sprite
-- receive and process click events to move the sprite
.touchEnabled = true
\slot "Tapped", (touch)->
\slot "TapBegan", (touch)->
sprite\perform Move(
1 -- duration in seconds
sprite.position -- start position
Expand All @@ -64,24 +93,24 @@ with Node!
<TabItem value="lua" label="Lua">

```lua title="Hello/init.lua"
-- Import modules
-- import modules
local Sprite <const> = require("Sprite")
local Node <const> = require("Node")
local Move <const> = require("Move")
local Ease <const> = require("Ease")

-- Create a sprite
-- create a sprite
local sprite = Sprite("Image/logo.png")

-- Create the root node of the game scene tree
-- create the root node of the game scene tree
local root = Node!

-- Mount the sprite to the root node
-- mount the sprite to the root node
root:addChild(sprite)

-- Receive and process click events to move the sprite
-- receive and process click events to move the sprite
root.touchEnabled = true
root:slot("Tapped", function(touch)
root:slot("TapBegan", function(touch)
sprite:perform(Move(
1, -- duration in seconds
sprite.position, -- start position
Expand All @@ -95,25 +124,25 @@ end)
<TabItem value="tl" label="Teal">

```tl title="Hello/init.tl"
-- Import modules
-- import modules
local Sprite <const> = require("Sprite")
local Node <const> = require("Node")
local Move <const> = require("Move")
local Ease <const> = require("Ease")
local type Touch = require("TouchType")
-- Create a sprite
-- create a sprite
local sprite = Sprite("Image/logo.png")
-- Create the root node of the game scene tree
-- create the root node of the game scene tree
local root = Node!
-- Mount the sprite to the root node
-- mount the sprite to the root node
root:addChild(sprite)
-- Receive and process click events to move the sprite
-- receive and process click events to move the sprite
root.touchEnabled = true
root:slot("Tapped", function(touch: Touch)
root:slot("TapBegan", function(touch: Touch)
sprite:perform(Move(
1, -- duration in seconds
sprite.position, -- start position
Expand All @@ -125,22 +154,23 @@ end)

</TabItem>
<TabItem value="ts" label="Typescript">

```ts title="Hello/init.ts"
// Import modules
// import modules
import {Ease, Move, Node, Slot, Sprite} from 'dora';

// Create a sprite
// create a sprite
const sprite = Sprite("Image/logo.png");

// Create the root node of the game scene tree
// create the root node of the game scene tree
const root = Node();

// Mount the sprite to the root node
// mount the sprite to the root node
root.addChild(sprite);

// Receive and process click events to move the sprite
// receive and process click events to move the sprite
root.touchEnabled = true;
root.slot(Slot.Tapped, touch => {
root.slot(Slot.TapBegan, touch => {
sprite.perform(
Move(
1, // duration in seconds
Expand All @@ -151,6 +181,7 @@ root.slot(Slot.Tapped, touch => {
);
});
```

</TabItem>
</Tabs>

Expand Down
Loading

0 comments on commit 0b9e547

Please sign in to comment.