gaesup-world 0.8.54 → 0.8.56
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +620 -620
- package/dist/gaesup/component/inner/character/index.js +1 -1
- package/dist/gaesup/component/inner/common/partsGroupRef.js +5 -3
- package/dist/gaesup/component/passive/character/index.js +1 -1
- package/dist/gaesup/controller/type.d.ts +5 -5
- package/index.ts +30 -30
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,620 +1,620 @@
|
|
|
1
|
-
# Gaesup World
|
|
2
|
-
|
|
3
|
-
[](https://www.npmjs.com/package/../../../src)
|
|
4
|
-
[](https://www.npmjs.com/package/../../../src)
|
|
5
|
-
|
|
6
|
-
### Web 3D Character Controller and World Platform Library
|
|
7
|
-
|
|
8
|
-
### 
|
|
9
|
-
|
|
10
|
-
## introduction
|
|
11
|
-
|
|
12
|
-
- Gaesup World is a library that uses `@react/three-fiber`,` @react/three-drei`, and `react-three-rapier` to provide control tools for characters, airplanes, cars, and more in a web 3D environment.
|
|
13
|
-
|
|
14
|
-
- This controller is designed to easily manage character movement, animation, and interaction. It allows for easy manipulation of characters or vehicles in a virtual world, and is also equipped with utilities like minimaps and joysticks.
|
|
15
|
-
|
|
16
|
-
## How to start
|
|
17
|
-
|
|
18
|
-
```tsx
|
|
19
|
-
import ...
|
|
20
|
-
|
|
21
|
-
export default function App() {
|
|
22
|
-
const CHARACTER_URL = S3 + "/gaesupyee.glb";
|
|
23
|
-
return (
|
|
24
|
-
<GaesupWorld
|
|
25
|
-
url={{
|
|
26
|
-
characterUrl: CHARACTER_URL,
|
|
27
|
-
}}
|
|
28
|
-
mode={{
|
|
29
|
-
...
|
|
30
|
-
}}
|
|
31
|
-
>
|
|
32
|
-
<Canvas>
|
|
33
|
-
<Physics>
|
|
34
|
-
<GaesupController />
|
|
35
|
-
</Physics>
|
|
36
|
-
</Canvas>
|
|
37
|
-
</GaesupWorld>
|
|
38
|
-
);
|
|
39
|
-
}
|
|
40
|
-
|
|
41
|
-
```
|
|
42
|
-
|
|
43
|
-
### Features
|
|
44
|
-
|
|
45
|
-
- 3D character control based on React Three Fiber.
|
|
46
|
-
- Simple API for controlling character movement and animation.
|
|
47
|
-
- Extensible structure for various customizations.
|
|
48
|
-
- Lightweight library for fast loading and performance optimization.
|
|
49
|
-
|
|
50
|
-
## Installation
|
|
51
|
-
|
|
52
|
-
```bash
|
|
53
|
-
npm install @react-three/fiber @react-three/drei three @types/three @react-three/rapier ../../../src
|
|
54
|
-
```
|
|
55
|
-
|
|
56
|
-
Or
|
|
57
|
-
|
|
58
|
-
```bash
|
|
59
|
-
yarn add @react-three/fiber @react-three/drei three @types/three @react-three/rapier ../../../src
|
|
60
|
-
```
|
|
61
|
-
|
|
62
|
-
## 4) How to Contribute
|
|
63
|
-
|
|
64
|
-
If you would like to contribute to this project, please follow these steps:
|
|
65
|
-
|
|
66
|
-
1. Fork the project.
|
|
67
|
-
2. go to dev branch ( git checkout dev ).
|
|
68
|
-
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`).
|
|
69
|
-
4. Push to the branch (git push origin dev).
|
|
70
|
-
5. Create a Pull Request.
|
|
71
|
-
|
|
72
|
-
## 5) License
|
|
73
|
-
|
|
74
|
-
This project is distributed under the MIT License.
|
|
75
|
-
|
|
76
|
-
- ## 1. [PlayerType](##PlayerType)
|
|
77
|
-
|
|
78
|
-
- [Character](#Character)
|
|
79
|
-
|
|
80
|
-
- [Vehicle](#Vehicle)
|
|
81
|
-
|
|
82
|
-
- [Airplane](#Airplane)
|
|
83
|
-
|
|
84
|
-
* ## 2. [Animation](Animation)
|
|
85
|
-
|
|
86
|
-
* ## 3. [Rideable](Rideable)
|
|
87
|
-
|
|
88
|
-
* ## 4. [Passive](Passive)
|
|
89
|
-
|
|
90
|
-
* ## 5. [Tools](#Tools)
|
|
91
|
-
|
|
92
|
-
- [joystick](#1joystick)
|
|
93
|
-
|
|
94
|
-
* [keyBoardTooltip](#keyBoardTooltip)
|
|
95
|
-
|
|
96
|
-
* [minimap](#MiniMap)
|
|
97
|
-
|
|
98
|
-
* [gameboy](##GameBoy)
|
|
99
|
-
|
|
100
|
-
- [GamePad](#GamePad)
|
|
101
|
-
|
|
102
|
-
- [ZoomButton](#ZoomButton)
|
|
103
|
-
|
|
104
|
-
- [JumpPortal](#JumpPortal)
|
|
105
|
-
|
|
106
|
-
# PlayerType
|
|
107
|
-
|
|
108
|
-
---
|
|
109
|
-
|
|
110
|
-
## Character
|
|
111
|
-
|
|
112
|
-
This is the character control in Gaesup World.
|
|
113
|
-
|
|
114
|
-
- Possible Camera Types
|
|
115
|
-
|
|
116
|
-
| Name | Info |
|
|
117
|
-
| ------ | --------------------------------------------------------------------------------------------- |
|
|
118
|
-
| Normal | Positioned parallel to the Z-axis from the character's location and not affected by rotation. |
|
|
119
|
-
| Orbit | Moves with the character and rotates according to the character's direction. |
|
|
120
|
-
|
|
121
|
-
- Controller Tools
|
|
122
|
-
|
|
123
|
-
| Name | Condition | Info |
|
|
124
|
-
| -------- | --------------------------- | ----------------------------------------------------------------------- |
|
|
125
|
-
| Keyboard | desktop | A standard keyboard tool. You can see where on the keyboard is clicked. |
|
|
126
|
-
| joystick | mobile (not normal control) | A joystick implementation tool. It works on mobile devices. |
|
|
127
|
-
| Gameboy | mobile | A Gameboy implementation tool. It works on mobile devices. |
|
|
128
|
-
|
|
129
|
-
## Vehicle
|
|
130
|
-
|
|
131
|
-
- This is the vehicle control in Gaesup World. Characters can board the vehicle.
|
|
132
|
-
|
|
133
|
-
* Possible Camera Types (only orbit type available)
|
|
134
|
-
|
|
135
|
-
| Name | Control | Info |
|
|
136
|
-
| ----- | ------------- | ---------------------------------------------------------------------------- |
|
|
137
|
-
| Orbit | Orbit Control | Moves with the character and rotates according to the character's direction. |
|
|
138
|
-
|
|
139
|
-
- Controller Tools
|
|
140
|
-
|
|
141
|
-
| Name | Condition | Info |
|
|
142
|
-
| -------- | --------- | ----------------------------------------------------------------------- |
|
|
143
|
-
| Keyboard | desktop | A standard keyboard tool. You can see where on the keyboard is clicked. |
|
|
144
|
-
| joystick | mobile | A joystick implementation tool. It works on mobile devices. |
|
|
145
|
-
| Gameboy | mobile | A Gameboy implementation tool. It works on mobile devices. |
|
|
146
|
-
|
|
147
|
-
## Airplane
|
|
148
|
-
|
|
149
|
-
the airplane control in Gaesup World. Characters can board the airplane.
|
|
150
|
-
|
|
151
|
-
- Possible Camera Types (only orbit type available)
|
|
152
|
-
|
|
153
|
-
| Name | Control | Info |
|
|
154
|
-
| ----- | ------------- | ---------------------------------------------------------------------------- |
|
|
155
|
-
| Orbit | Orbit Control | Moves with the character and rotates according to the character's direction. |
|
|
156
|
-
|
|
157
|
-
- Controller Tools
|
|
158
|
-
|
|
159
|
-
| Name | Condition | Info |
|
|
160
|
-
| -------- | --------- | ----------------------------------------------------------------------- |
|
|
161
|
-
| Keyboard | desktop | A standard keyboard tool. You can see where on the keyboard is clicked. |
|
|
162
|
-
| joystick | mobile | A joystick implementation tool. It works on mobile devices. |
|
|
163
|
-
| Gameboy | mobile | A Gameboy implementation tool. It works on mobile devices. |
|
|
164
|
-
|
|
165
|
-
# Animation
|
|
166
|
-
|
|
167
|
-
- Animation refers to the method of controlling animations for characters and other elements in the Gaesup World.
|
|
168
|
-
|
|
169
|
-
# Rideable
|
|
170
|
-
|
|
171
|
-
- Rideable objects are objects that can be ridden. They detect collisions and allow the character to board when contact is made. Currently, two types of objects, 'vehicle' and 'airplane', can be ridden.
|
|
172
|
-
|
|
173
|
-
example)
|
|
174
|
-
|
|
175
|
-
<img src="https://jiggloghttps.s3.ap-northeast-2.amazonaws.com/images/rideable.gif" alt="Rideable" style="zoom:150%;" />
|
|
176
|
-
|
|
177
|
-
### (1) Example
|
|
178
|
-
|
|
179
|
-
```tsx
|
|
180
|
-
export default function App() {
|
|
181
|
-
// Define URLs
|
|
182
|
-
const CHARACTER_URL = S3 + "/gaesup.glb";
|
|
183
|
-
const AIRPLANE_URL = S3 + "/air.glb";
|
|
184
|
-
const VEHICLE_URL = S3 + "/kart.glb";
|
|
185
|
-
const WHEEL_URL = S3 + "/wheel.glb";
|
|
186
|
-
|
|
187
|
-
return (
|
|
188
|
-
<GaesupWorld
|
|
189
|
-
// ...props defined here
|
|
190
|
-
>
|
|
191
|
-
<Canvas
|
|
192
|
-
// ...props defined here
|
|
193
|
-
>
|
|
194
|
-
<Physics>
|
|
195
|
-
<GaesupController />
|
|
196
|
-
|
|
197
|
-
{/* Import Rideable component inside and pass the arguments as shown below */}
|
|
198
|
-
<Rideable
|
|
199
|
-
objectkey="1"
|
|
200
|
-
objectType="vehicle"
|
|
201
|
-
isRiderOn={true}
|
|
202
|
-
url={VEHICLE_URL}
|
|
203
|
-
wheelUrl={WHEEL_URL}
|
|
204
|
-
offset={V3(0, 0.5, 0)}
|
|
205
|
-
position={V3(-10, 5, 10)}
|
|
206
|
-
/>
|
|
207
|
-
<Rideable
|
|
208
|
-
objectkey="2"
|
|
209
|
-
objectType="vehicle"
|
|
210
|
-
isRiderOn={false}
|
|
211
|
-
url={VEHICLE_URL}
|
|
212
|
-
wheelUrl={WHEEL_URL}
|
|
213
|
-
position={V3(-20, 5, 10)}
|
|
214
|
-
/>
|
|
215
|
-
<Rideable
|
|
216
|
-
objectkey="3"
|
|
217
|
-
objectType="airplane"
|
|
218
|
-
isRiderOn={true}
|
|
219
|
-
url={AIRPLANE_URL}
|
|
220
|
-
offset={V3(0, 0.5, 0)}
|
|
221
|
-
position={V3(10, 5, 10)}
|
|
222
|
-
/>
|
|
223
|
-
<Rideable
|
|
224
|
-
objectkey="4"
|
|
225
|
-
objectType="airplane"
|
|
226
|
-
isRiderOn={false}
|
|
227
|
-
url={AIRPLANE_URL}
|
|
228
|
-
position={V3(20, 5, 10)}
|
|
229
|
-
/>
|
|
230
|
-
</Physics>
|
|
231
|
-
</Canvas>
|
|
232
|
-
</GaesupWorld>
|
|
233
|
-
);
|
|
234
|
-
}
|
|
235
|
-
```
|
|
236
|
-
|
|
237
|
-
### 2) Precautions
|
|
238
|
-
|
|
239
|
-
- The `objectkey` must be unique.
|
|
240
|
-
|
|
241
|
-
### 3) Props
|
|
242
|
-
|
|
243
|
-
| Prop Name | Type | Required | Description | Default Value |
|
|
244
|
-
| -------------- | ----------------------- | -------- | ----------------------------------------------- | -------------- |
|
|
245
|
-
| `objectkey` | string | Required | Unique identifier for the rideable object | None |
|
|
246
|
-
| `objectType` | "vehicle" or "airplane" | Optional | Type of the rideable object | `undefined` |
|
|
247
|
-
| `isRiderOn` | boolean | Optional | Whether a rider is on the rideable object | `false` |
|
|
248
|
-
| `url` | string | Optional | 3D model URL for the rideable object | `null` |
|
|
249
|
-
| `wheelUrl` | string | Optional | Wheel model URL for "vehicle" type rideables | `null` |
|
|
250
|
-
| `position` | THREE.Vector3 | Optional | Initial position of the rideable object | `(0, 0, 0)` |
|
|
251
|
-
| `rotation` | THREE.Euler | Optional | Initial rotation angle of the rideable object | `(0, 0, 0)` |
|
|
252
|
-
| `offset` | THREE.Vector3 | Optional | Initial position offset for the rideable object | `(0, 0, 0)` |
|
|
253
|
-
| `visible` | boolean | Optional | Visibility of the rideable object | `true` |
|
|
254
|
-
| `vehicleSize` | THREE.Vector3 | Optional | Size of the "vehicle" type rideable object | Rapier default |
|
|
255
|
-
| `wheelSize` | THREE.Vector3 | Optional | Size of the wheel for "vehicle" type rideables | Rapier default |
|
|
256
|
-
| `airplaneSize` | THREE.Vector3 | Optional | Size of the "airplane" type rideable object | Rapier default |
|
|
257
|
-
|
|
258
|
-
### 4) Features
|
|
259
|
-
|
|
260
|
-
1. **Support for Various Rideable Objects:** The Rideable component can render a variety of rideable objects, including "vehicle" and "airplane" types. It can render the 3D models of each object and allow interactions with them.
|
|
261
|
-
2. **Customizable Properties:** You can easily configure the initial state, size, model URLs, visibility, and more of rideable objects using component properties.
|
|
262
|
-
3. **Interaction with Riders:** The Rideable component supports interactions required for a rider to board and move with rideable objects.
|
|
263
|
-
|
|
264
|
-
### 5) Advantages
|
|
265
|
-
|
|
266
|
-
- **Modularity and Reusability:** The Rideable component is modular and can be easily integrated with other components, increasing code reusability and facilitating maintenance.
|
|
267
|
-
|
|
268
|
-
- **Rapid Development:** By using the `useRideable` hook, which manages the physics engine and rideable object management, developers can quickly implement and render rideable objects, reducing development time.
|
|
269
|
-
|
|
270
|
-
- **Real-time Interaction:** Leveraging the Rapier physics engine allows for real-time handling of rideable object movements and collision checks, providing a high level of interaction in games or simulations.
|
|
271
|
-
|
|
272
|
-
- **Flexible Customization:** You can customize the appearance and behavior of each rideable object using properties, making it suitable for various game or simulation environments.
|
|
273
|
-
|
|
274
|
-
# Passive
|
|
275
|
-
|
|
276
|
-
---
|
|
277
|
-
|
|
278
|
-
under construct
|
|
279
|
-
|
|
280
|
-
# GaeSupProps
|
|
281
|
-
|
|
282
|
-
---
|
|
283
|
-
|
|
284
|
-
The `GaeSupProps` component is a React component used in a 3D environment. It is designed to represent various types of props or objects within the scene. This component can be used to create props with different types, text labels, and positions for visualization in a 3D space.
|
|
285
|
-
|
|
286
|
-
### (1) props
|
|
287
|
-
|
|
288
|
-
The `GaeSupProps` component accepts the following props:
|
|
289
|
-
|
|
290
|
-
- `type` (optional): A string specifying the type of the prop. It can be either `"normal"` or `"ground"`. Defaults to `"normal"` if not provided.
|
|
291
|
-
- `text` (optional): A string representing the text label associated with the prop. This label can provide additional information about the prop. If not provided, no label will be displayed.
|
|
292
|
-
- `position` (optional): An array of three numbers `[x, y, z]` specifying the initial position of the prop in the 3D space. If not provided, the prop will be positioned at the origin `[0, 0, 0]`.
|
|
293
|
-
- `children` (required): This prop should contain the 3D content that makes up the visual representation of the prop. It can include any 3D objects or components you want to render within the prop.
|
|
294
|
-
|
|
295
|
-
### (2) example
|
|
296
|
-
|
|
297
|
-
- To use the `GaeSupProps` component, you need to import it and include it in your React component tree. Here's an example of how to use it:
|
|
298
|
-
|
|
299
|
-
```tsx
|
|
300
|
-
import { GaeSupProps } from "./GaeSupProps";
|
|
301
|
-
|
|
302
|
-
function MyScene() {
|
|
303
|
-
return (
|
|
304
|
-
<GaeSupProps type="normal" text="My Prop" position={[3, 1, -2]}>
|
|
305
|
-
{/* 3D content goes here */}
|
|
306
|
-
</GaeSupProps>
|
|
307
|
-
);
|
|
308
|
-
}
|
|
309
|
-
```
|
|
310
|
-
|
|
311
|
-
- In this example, we've created a `GaeSupProps` component with a `"normal"` type, a text label of `"My Prop"`, and a specific position in 3D space.
|
|
312
|
-
|
|
313
|
-
### (3) Behavior
|
|
314
|
-
|
|
315
|
-
- The `GaeSupProps` component also calculates the size and center of the 3D content it contains. It then updates a `minimap` object with this information, which can be useful for tracking the props within the scene.
|
|
316
|
-
|
|
317
|
-
- Additionally, the component uses the `useEffect` hook to dispatch updates to the context, ensuring that changes to the `minimap` object are reflected in the sce
|
|
318
|
-
|
|
319
|
-
# Tools
|
|
320
|
-
|
|
321
|
-
- Various tools that assist with character control in GaesupWorld
|
|
322
|
-
|
|
323
|
-
## GameBoy
|
|
324
|
-
|
|
325
|
-
- The GameBoy component is a controller interface that emulates GameBoy-like directional buttons. It is primarily intended for mobile usage.
|
|
326
|
-
|
|
327
|
-
### (1) props
|
|
328
|
-
|
|
329
|
-
| Prop Name | Type | Required | Description | Default Value |
|
|
330
|
-
| -------------------- | --------------- | -------- | ------------------------------------ | ------------- |
|
|
331
|
-
| `gamePadStyle` | object (styles) | Optional | Style for the GamePad container | `undefined` |
|
|
332
|
-
| `gamePadButtonStyle` | object (styles) | Optional | Style for individual GamePad buttons | `undefined` |
|
|
333
|
-
| `label` | string | Optional | Custom label for the buttons | `undefined` |
|
|
334
|
-
|
|
335
|
-
### (2) example
|
|
336
|
-
|
|
337
|
-
```tsx
|
|
338
|
-
import { GameBoy } from "./GameBoy";
|
|
339
|
-
import { GaesupWorldContext } from "../../world/context";
|
|
340
|
-
|
|
341
|
-
const App = () => {
|
|
342
|
-
return (
|
|
343
|
-
<GaesupWorld>
|
|
344
|
-
{/* ... */}
|
|
345
|
-
<GameBoy
|
|
346
|
-
gameboyStyle={gameboyStyle}
|
|
347
|
-
gameboyButtonStyle={gameboyButtonStyle}
|
|
348
|
-
/>
|
|
349
|
-
{/* ... */}
|
|
350
|
-
</GaesupWorld>
|
|
351
|
-
);
|
|
352
|
-
};
|
|
353
|
-
```
|
|
354
|
-
|
|
355
|
-
### (3) Key Features:
|
|
356
|
-
|
|
357
|
-
- **Direction Buttons:** Implements buttons for directional input (forward, backward, left, right) based on the `GameBoyDirections` array.
|
|
358
|
-
- **Context-aware Rendering:** Renders the component based on the `mode.controller` value from the `GaesupWorldContext`.
|
|
359
|
-
- **Custom Styling:** Provides `gameboyStyle` and `gameboyButtonStyle` properties for styling customization.
|
|
360
|
-
|
|
361
|
-
### (4) How to Use
|
|
362
|
-
|
|
363
|
-
To use the `GameBoy` component:
|
|
364
|
-
|
|
365
|
-
1. Place the `GameBoy` component within your component tree.
|
|
366
|
-
2. Customize the appearance by defining styles in the `gameboyStyle` and `gameboyButtonStyle` properties.
|
|
367
|
-
3. The component renders buttons based on the `GameBoyDirections` array.
|
|
368
|
-
|
|
369
|
-
## GamePad
|
|
370
|
-
|
|
371
|
-
- The GamePad component provides a customizable controller interface that supports various controller modes, such as joysticks and GameBoys, making it versatile for different input scenarios.
|
|
372
|
-
|
|
373
|
-
### (1) props
|
|
374
|
-
|
|
375
|
-
| Prop Name | Type | Required | Description | Default Value |
|
|
376
|
-
| -------------------- | --------------- | -------- | ------------------------------------ | ------------- |
|
|
377
|
-
| `gamePadStyle` | object (styles) | Optional | Style for the GamePad container | `undefined` |
|
|
378
|
-
| `gamePadButtonStyle` | object (styles) | Optional | Style for individual GamePad buttons | `undefined` |
|
|
379
|
-
| `label` | string | Optional | Custom label for the buttons | `undefined` |
|
|
380
|
-
|
|
381
|
-
### (2) example
|
|
382
|
-
|
|
383
|
-
```tsx
|
|
384
|
-
import { GamePad } from "./GamePad";
|
|
385
|
-
import { GaesupWorldContext } from "../../world/context";
|
|
386
|
-
|
|
387
|
-
const App = () => {
|
|
388
|
-
return (
|
|
389
|
-
<GaesupWorld>
|
|
390
|
-
{/* ... */}
|
|
391
|
-
<GamePad
|
|
392
|
-
gamePadStyle={gamePadStyle}
|
|
393
|
-
gamePadButtonStyle={gamePadButtonStyle}
|
|
394
|
-
/>
|
|
395
|
-
{/* ... */}
|
|
396
|
-
</GaesupWorld>
|
|
397
|
-
);
|
|
398
|
-
};
|
|
399
|
-
```
|
|
400
|
-
|
|
401
|
-
### (3) Key Features
|
|
402
|
-
|
|
403
|
-
- **Dynamic Button Rendering:** Dynamically generates buttons based on the `control` object in the `GaesupWorldContext`.
|
|
404
|
-
- **Universal Usage:** Compatible with various controller modes like joysticks and GameBoys.
|
|
405
|
-
- **Custom Styling:** Allows customization of the GamePad's appearance using the `gamePadStyle` and `gamePadButtonStyle` properties.
|
|
406
|
-
|
|
407
|
-
### (4) How to Use
|
|
408
|
-
|
|
409
|
-
1. Include the `GamePad` component within your component tree.
|
|
410
|
-
2. Customize the appearance using the `gamePadStyle` and `gamePadButtonStyle` properties.
|
|
411
|
-
3. The component dynamically renders buttons based on the `control` mode.
|
|
412
|
-
|
|
413
|
-
## joystick
|
|
414
|
-
|
|
415
|
-
---
|
|
416
|
-
|
|
417
|
-
- The joystick component provides a virtual joystick interface, primarily intended for mobile environments. This component allows you to simulate joystick-like input on mobile devices. Additionally, you can prevent position jitter, which can occur on mobile devices, by using the `scrollBlock` option in the `GaesupWorld` component.
|
|
418
|
-
|
|
419
|
-
### (1) props
|
|
420
|
-
|
|
421
|
-
| Prop Name | Type | Required | Description | Default Value |
|
|
422
|
-
| ------------------- | --------------- | -------- | --------------------------- | ------------- |
|
|
423
|
-
| `joystickStyle` | object (styles) | Optional | Style for the joystick | `undefined` |
|
|
424
|
-
| `joystickBallStyle` | object (styles) | Optional | Style for the joystick ball | `undefined` |
|
|
425
|
-
|
|
426
|
-
### (2) example
|
|
427
|
-
|
|
428
|
-
```jsx
|
|
429
|
-
const MyComponent = () => {
|
|
430
|
-
const joystickStyle = {
|
|
431
|
-
/* joystickStyle */
|
|
432
|
-
};
|
|
433
|
-
const joystickBallStyle = {
|
|
434
|
-
/* joystickBallStyle */
|
|
435
|
-
};
|
|
436
|
-
|
|
437
|
-
return (
|
|
438
|
-
<GaesupWorld>
|
|
439
|
-
{/* ... */}
|
|
440
|
-
<joystick
|
|
441
|
-
joystickStyle={joystickStyle}
|
|
442
|
-
joystickBallStyle={joystickBallStyle}
|
|
443
|
-
/>
|
|
444
|
-
{/* ... */}
|
|
445
|
-
</GaesupWorld>
|
|
446
|
-
);
|
|
447
|
-
};
|
|
448
|
-
```
|
|
449
|
-
|
|
450
|
-
### (3) Key Features:
|
|
451
|
-
|
|
452
|
-
- **joystick Interface:** Provides a joystick-like user input interface, suitable for mobile devices.
|
|
453
|
-
- **Customization:** You can customize the style of the joystick component by adjusting the styles of the joystick and the joystick ball using the `joystickBallStyle` and `joystickStyle` properties.
|
|
454
|
-
- **Responsive and Interactive:** It supports various input devices and responds to both mouse and mobile touch events for controlling movement.
|
|
455
|
-
|
|
456
|
-
## 4) JumpPortal
|
|
457
|
-
|
|
458
|
-
- The `JumpPortal` component represents a clickable portal that allows users to teleport to a specified location within a 3D world. This component can be used to create interactive teleportation points in your application.
|
|
459
|
-
|
|
460
|
-
### (1) props
|
|
461
|
-
|
|
462
|
-
| Prop Name | Type | Required | Description | Default Value |
|
|
463
|
-
| ----------------- | ------------- | -------- | ----------------------------------------------------------- | ------------- |
|
|
464
|
-
| `text` | string | Optional | The text to display on the portal. | `undefined` |
|
|
465
|
-
| `position` | THREE.Vector3 | Required | The target position to teleport to using a `THREE.Vector3`. | None |
|
|
466
|
-
| `jumpPortalStyle` | CSSProperties | Optional | CSS styles for customizing the appearance of the portal. | `undefined` |
|
|
467
|
-
|
|
468
|
-
### (2) example
|
|
469
|
-
|
|
470
|
-
- To use the `JumpPortal` component, you can import it and include it in your React application as follows:
|
|
471
|
-
|
|
472
|
-
```tsx
|
|
473
|
-
import { JumpPortal } from "./JumpPortal";
|
|
474
|
-
import * as THREE from "three";
|
|
475
|
-
|
|
476
|
-
const App = () => {
|
|
477
|
-
return (
|
|
478
|
-
<GaesupWorld>
|
|
479
|
-
{/* ... */}
|
|
480
|
-
<JumpPortal
|
|
481
|
-
text="Teleport"
|
|
482
|
-
position={new THREE.Vector3(10, 0, 5)}
|
|
483
|
-
jumpPortalStyle={{ backgroundColor: "blue", color: "white" }}
|
|
484
|
-
/>
|
|
485
|
-
{/* ... */}
|
|
486
|
-
</GaesupWorld>
|
|
487
|
-
);
|
|
488
|
-
};
|
|
489
|
-
```
|
|
490
|
-
|
|
491
|
-
## KeyBoardToolTip
|
|
492
|
-
|
|
493
|
-
---
|
|
494
|
-
|
|
495
|
-
- The KeyBoardToolTip component is designed to visually represent a keyboard controller interface, providing a visual representation of each key and its associated action.
|
|
496
|
-
|
|
497
|
-
### Key Features
|
|
498
|
-
|
|
499
|
-
- **Visualizing Keyboard Keys:** Visualizes all keyboard keys in an array format.
|
|
500
|
-
- **State Animation:** Reflects the currently active keys and their associated actions by displaying them differently to provide user feedback.
|
|
501
|
-
- **Custom Styling:** Provides various styling properties for customizing key caps' appearance.
|
|
502
|
-
|
|
503
|
-
### How to Use
|
|
504
|
-
|
|
505
|
-
1. Include the `KeyBoardToolTip` component within the `GaesupWorld` component.
|
|
506
|
-
2. Define the `control` mode as "keyboard" in the `mode` property.
|
|
507
|
-
3. The component visualizes each keyboard key based on the `KeyBoardAll` constant and applies different styles for currently active keys.
|
|
508
|
-
4. (Optional) Customize the styles using the `keyBoardToolTipInnerStyle`, `selectedKeyCapStyle`, `notSelectedkeyCapStyle`, and `keyCapStyle` properties.
|
|
509
|
-
|
|
510
|
-
### Example:
|
|
511
|
-
|
|
512
|
-
```tsx
|
|
513
|
-
import { KeyBoardToolTip } from "./KeyBoardToolTip";
|
|
514
|
-
import { GaesupWorldContext } from "../../world/context";
|
|
515
|
-
|
|
516
|
-
const App = () => {
|
|
517
|
-
return (
|
|
518
|
-
<GaesupWorld>
|
|
519
|
-
{/* ... */}
|
|
520
|
-
<KeyBoardToolTip
|
|
521
|
-
keyBoardToolTipInnerStyle={keyBoardToolTipInnerStyle}
|
|
522
|
-
selectedKeyCapStyle={selectedKeyCapStyle}
|
|
523
|
-
notSelectedkeyCapStyle={notSelectedkeyCapStyle}
|
|
524
|
-
keyCapStyle={keyCapStyle}
|
|
525
|
-
/>
|
|
526
|
-
{/* ... */}
|
|
527
|
-
</GaesupWorld>
|
|
528
|
-
);
|
|
529
|
-
};
|
|
530
|
-
```
|
|
531
|
-
|
|
532
|
-
## MiniMap
|
|
533
|
-
|
|
534
|
-
---
|
|
535
|
-
|
|
536
|
-
- The MiniMap component is used to display a small map of the user's location and the surrounding environment within a 3D world.
|
|
537
|
-
|
|
538
|
-
### (1) props
|
|
539
|
-
|
|
540
|
-
| Prop Name | Type | Required | Description | Default Value |
|
|
541
|
-
| ---------------- | --------------- | -------- | --------------------------------------------- | ------------- |
|
|
542
|
-
| `innerStyle` | object (styles) | Optional | Style for the inner MiniMap container | `undefined` |
|
|
543
|
-
| `textStyle` | object (styles) | Optional | Style for text within the MiniMap | `undefined` |
|
|
544
|
-
| `objectStyle` | object (styles) | Optional | Style for objects within the MiniMap | `undefined` |
|
|
545
|
-
| `avatarStyle` | object (styles) | Optional | Style for avatars within the MiniMap | `undefined` |
|
|
546
|
-
| `scaleStyle` | object (styles) | Optional | Style for the scale control of the MiniMap | `undefined` |
|
|
547
|
-
| `directionStyle` | object (styles) | Optional | Style for direction indicators in the MiniMap | `undefined` |
|
|
548
|
-
| `plusMinusStyle` | object (styles) | Optional | Style for plus/minus controls in the MiniMap | `undefined` |
|
|
549
|
-
|
|
550
|
-
### 2) example
|
|
551
|
-
|
|
552
|
-
```tsx
|
|
553
|
-
import { MiniMap } from "./MiniMap";
|
|
554
|
-
|
|
555
|
-
const App = () => {
|
|
556
|
-
return (
|
|
557
|
-
<GaesupWorld>
|
|
558
|
-
{/* ... */}
|
|
559
|
-
<MiniMap
|
|
560
|
-
minimapStyle={minimapStyle}
|
|
561
|
-
innerStyle={innerStyle}
|
|
562
|
-
// Pass other style properties as needed
|
|
563
|
-
/>
|
|
564
|
-
{/* ... */}
|
|
565
|
-
</GaesupWorld>
|
|
566
|
-
);
|
|
567
|
-
};
|
|
568
|
-
```
|
|
569
|
-
|
|
570
|
-
### 3) Key Features
|
|
571
|
-
|
|
572
|
-
- **Dynamic Scaling:** Allows users to dynamically adjust the size of the map.
|
|
573
|
-
- **Direction Indicators:** Visualizes directions such as East, West, South, and North.
|
|
574
|
-
- **Custom Styling:** Allows customization of the MiniMap and its internal elements.
|
|
575
|
-
- **Mouse Wheel Support:** Supports adjusting the map's scale using the mouse wheel.
|
|
576
|
-
|
|
577
|
-
### 4) How to Use
|
|
578
|
-
|
|
579
|
-
1. Include the `MiniMap` component within your component tree.
|
|
580
|
-
2. Customize the appearance using the `minimapStyle`, `innerStyle`, `textStyle`, `objectStyle`, `avatarStyle`, `scaleStyle`, `directionStyle`, and `plusMinusStyle` properties as needed.
|
|
581
|
-
3. The component updates the MiniMap based on the user's current position and direction.
|
|
582
|
-
|
|
583
|
-
## ZoomButton
|
|
584
|
-
|
|
585
|
-
---
|
|
586
|
-
|
|
587
|
-
- The ZoomButton component is used to move the camera to a specific location and control the camera's zoom, primarily used for zooming to a target.
|
|
588
|
-
|
|
589
|
-
### (1) props
|
|
590
|
-
|
|
591
|
-
| Prop Name | Type | Required | Description | Default Value |
|
|
592
|
-
| ----------------- | --------------- | -------- | ---------------------------------------------------------- | ------------- |
|
|
593
|
-
| `position` | THREE.Vector3 | Required | Target position for the camera to move to | None |
|
|
594
|
-
| `children` | React.ReactNode | Optional | React nodes to render within the button | `undefined` |
|
|
595
|
-
| `target` | THREE.Vector3 | Optional | Target position for the camera to look at | `undefined` |
|
|
596
|
-
| `keepBlocking` | boolean | Optional | Determines whether to keep blocking while camera is moving | `undefined` |
|
|
597
|
-
| `zoomButtonStyle` | object (styles) | Optional | Style for the ZoomButton component | `undefined` |
|
|
598
|
-
|
|
599
|
-
### (2) example
|
|
600
|
-
|
|
601
|
-
```tsx
|
|
602
|
-
import { ZoomButton } from "./ZoomButton";
|
|
603
|
-
import * as THREE from "three";
|
|
604
|
-
|
|
605
|
-
const App = () => {
|
|
606
|
-
return (
|
|
607
|
-
<GaesupWorld>
|
|
608
|
-
{/* ... */}
|
|
609
|
-
<ZoomButton position={new THREE.Vector3(0, 0, 5)}>{childern}</ZoomButton>
|
|
610
|
-
{/* ... */}
|
|
611
|
-
</GaesupWorld>
|
|
612
|
-
);
|
|
613
|
-
};
|
|
614
|
-
```
|
|
615
|
-
|
|
616
|
-
### (3) How to Use
|
|
617
|
-
|
|
618
|
-
1. Place the `ZoomButton` component in your component tree at the desired location.
|
|
619
|
-
2. Define the `position` prop to specify the location the camera should move to.
|
|
620
|
-
3. When the button is clicked, the camera will move to the specified position.
|
|
1
|
+
# Gaesup World
|
|
2
|
+
|
|
3
|
+
[](https://www.npmjs.com/package/../../../src)
|
|
4
|
+
[](https://www.npmjs.com/package/../../../src)
|
|
5
|
+
|
|
6
|
+
### Web 3D Character Controller and World Platform Library
|
|
7
|
+
|
|
8
|
+
### 
|
|
9
|
+
|
|
10
|
+
## introduction
|
|
11
|
+
|
|
12
|
+
- Gaesup World is a library that uses `@react/three-fiber`,` @react/three-drei`, and `react-three-rapier` to provide control tools for characters, airplanes, cars, and more in a web 3D environment.
|
|
13
|
+
|
|
14
|
+
- This controller is designed to easily manage character movement, animation, and interaction. It allows for easy manipulation of characters or vehicles in a virtual world, and is also equipped with utilities like minimaps and joysticks.
|
|
15
|
+
|
|
16
|
+
## How to start
|
|
17
|
+
|
|
18
|
+
```tsx
|
|
19
|
+
import ...
|
|
20
|
+
|
|
21
|
+
export default function App() {
|
|
22
|
+
const CHARACTER_URL = S3 + "/gaesupyee.glb";
|
|
23
|
+
return (
|
|
24
|
+
<GaesupWorld
|
|
25
|
+
url={{
|
|
26
|
+
characterUrl: CHARACTER_URL,
|
|
27
|
+
}}
|
|
28
|
+
mode={{
|
|
29
|
+
...
|
|
30
|
+
}}
|
|
31
|
+
>
|
|
32
|
+
<Canvas>
|
|
33
|
+
<Physics>
|
|
34
|
+
<GaesupController />
|
|
35
|
+
</Physics>
|
|
36
|
+
</Canvas>
|
|
37
|
+
</GaesupWorld>
|
|
38
|
+
);
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
### Features
|
|
44
|
+
|
|
45
|
+
- 3D character control based on React Three Fiber.
|
|
46
|
+
- Simple API for controlling character movement and animation.
|
|
47
|
+
- Extensible structure for various customizations.
|
|
48
|
+
- Lightweight library for fast loading and performance optimization.
|
|
49
|
+
|
|
50
|
+
## Installation
|
|
51
|
+
|
|
52
|
+
```bash
|
|
53
|
+
npm install @react-three/fiber @react-three/drei three @types/three @react-three/rapier ../../../src
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
Or
|
|
57
|
+
|
|
58
|
+
```bash
|
|
59
|
+
yarn add @react-three/fiber @react-three/drei three @types/three @react-three/rapier ../../../src
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
## 4) How to Contribute
|
|
63
|
+
|
|
64
|
+
If you would like to contribute to this project, please follow these steps:
|
|
65
|
+
|
|
66
|
+
1. Fork the project.
|
|
67
|
+
2. go to dev branch ( git checkout dev ).
|
|
68
|
+
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`).
|
|
69
|
+
4. Push to the branch (git push origin dev).
|
|
70
|
+
5. Create a Pull Request.
|
|
71
|
+
|
|
72
|
+
## 5) License
|
|
73
|
+
|
|
74
|
+
This project is distributed under the MIT License.
|
|
75
|
+
|
|
76
|
+
- ## 1. [PlayerType](##PlayerType)
|
|
77
|
+
|
|
78
|
+
- [Character](#Character)
|
|
79
|
+
|
|
80
|
+
- [Vehicle](#Vehicle)
|
|
81
|
+
|
|
82
|
+
- [Airplane](#Airplane)
|
|
83
|
+
|
|
84
|
+
* ## 2. [Animation](Animation)
|
|
85
|
+
|
|
86
|
+
* ## 3. [Rideable](Rideable)
|
|
87
|
+
|
|
88
|
+
* ## 4. [Passive](Passive)
|
|
89
|
+
|
|
90
|
+
* ## 5. [Tools](#Tools)
|
|
91
|
+
|
|
92
|
+
- [joystick](#1joystick)
|
|
93
|
+
|
|
94
|
+
* [keyBoardTooltip](#keyBoardTooltip)
|
|
95
|
+
|
|
96
|
+
* [minimap](#MiniMap)
|
|
97
|
+
|
|
98
|
+
* [gameboy](##GameBoy)
|
|
99
|
+
|
|
100
|
+
- [GamePad](#GamePad)
|
|
101
|
+
|
|
102
|
+
- [ZoomButton](#ZoomButton)
|
|
103
|
+
|
|
104
|
+
- [JumpPortal](#JumpPortal)
|
|
105
|
+
|
|
106
|
+
# PlayerType
|
|
107
|
+
|
|
108
|
+
---
|
|
109
|
+
|
|
110
|
+
## Character
|
|
111
|
+
|
|
112
|
+
This is the character control in Gaesup World.
|
|
113
|
+
|
|
114
|
+
- Possible Camera Types
|
|
115
|
+
|
|
116
|
+
| Name | Info |
|
|
117
|
+
| ------ | --------------------------------------------------------------------------------------------- |
|
|
118
|
+
| Normal | Positioned parallel to the Z-axis from the character's location and not affected by rotation. |
|
|
119
|
+
| Orbit | Moves with the character and rotates according to the character's direction. |
|
|
120
|
+
|
|
121
|
+
- Controller Tools
|
|
122
|
+
|
|
123
|
+
| Name | Condition | Info |
|
|
124
|
+
| -------- | --------------------------- | ----------------------------------------------------------------------- |
|
|
125
|
+
| Keyboard | desktop | A standard keyboard tool. You can see where on the keyboard is clicked. |
|
|
126
|
+
| joystick | mobile (not normal control) | A joystick implementation tool. It works on mobile devices. |
|
|
127
|
+
| Gameboy | mobile | A Gameboy implementation tool. It works on mobile devices. |
|
|
128
|
+
|
|
129
|
+
## Vehicle
|
|
130
|
+
|
|
131
|
+
- This is the vehicle control in Gaesup World. Characters can board the vehicle.
|
|
132
|
+
|
|
133
|
+
* Possible Camera Types (only orbit type available)
|
|
134
|
+
|
|
135
|
+
| Name | Control | Info |
|
|
136
|
+
| ----- | ------------- | ---------------------------------------------------------------------------- |
|
|
137
|
+
| Orbit | Orbit Control | Moves with the character and rotates according to the character's direction. |
|
|
138
|
+
|
|
139
|
+
- Controller Tools
|
|
140
|
+
|
|
141
|
+
| Name | Condition | Info |
|
|
142
|
+
| -------- | --------- | ----------------------------------------------------------------------- |
|
|
143
|
+
| Keyboard | desktop | A standard keyboard tool. You can see where on the keyboard is clicked. |
|
|
144
|
+
| joystick | mobile | A joystick implementation tool. It works on mobile devices. |
|
|
145
|
+
| Gameboy | mobile | A Gameboy implementation tool. It works on mobile devices. |
|
|
146
|
+
|
|
147
|
+
## Airplane
|
|
148
|
+
|
|
149
|
+
the airplane control in Gaesup World. Characters can board the airplane.
|
|
150
|
+
|
|
151
|
+
- Possible Camera Types (only orbit type available)
|
|
152
|
+
|
|
153
|
+
| Name | Control | Info |
|
|
154
|
+
| ----- | ------------- | ---------------------------------------------------------------------------- |
|
|
155
|
+
| Orbit | Orbit Control | Moves with the character and rotates according to the character's direction. |
|
|
156
|
+
|
|
157
|
+
- Controller Tools
|
|
158
|
+
|
|
159
|
+
| Name | Condition | Info |
|
|
160
|
+
| -------- | --------- | ----------------------------------------------------------------------- |
|
|
161
|
+
| Keyboard | desktop | A standard keyboard tool. You can see where on the keyboard is clicked. |
|
|
162
|
+
| joystick | mobile | A joystick implementation tool. It works on mobile devices. |
|
|
163
|
+
| Gameboy | mobile | A Gameboy implementation tool. It works on mobile devices. |
|
|
164
|
+
|
|
165
|
+
# Animation
|
|
166
|
+
|
|
167
|
+
- Animation refers to the method of controlling animations for characters and other elements in the Gaesup World.
|
|
168
|
+
|
|
169
|
+
# Rideable
|
|
170
|
+
|
|
171
|
+
- Rideable objects are objects that can be ridden. They detect collisions and allow the character to board when contact is made. Currently, two types of objects, 'vehicle' and 'airplane', can be ridden.
|
|
172
|
+
|
|
173
|
+
example)
|
|
174
|
+
|
|
175
|
+
<img src="https://jiggloghttps.s3.ap-northeast-2.amazonaws.com/images/rideable.gif" alt="Rideable" style="zoom:150%;" />
|
|
176
|
+
|
|
177
|
+
### (1) Example
|
|
178
|
+
|
|
179
|
+
```tsx
|
|
180
|
+
export default function App() {
|
|
181
|
+
// Define URLs
|
|
182
|
+
const CHARACTER_URL = S3 + "/gaesup.glb";
|
|
183
|
+
const AIRPLANE_URL = S3 + "/air.glb";
|
|
184
|
+
const VEHICLE_URL = S3 + "/kart.glb";
|
|
185
|
+
const WHEEL_URL = S3 + "/wheel.glb";
|
|
186
|
+
|
|
187
|
+
return (
|
|
188
|
+
<GaesupWorld
|
|
189
|
+
// ...props defined here
|
|
190
|
+
>
|
|
191
|
+
<Canvas
|
|
192
|
+
// ...props defined here
|
|
193
|
+
>
|
|
194
|
+
<Physics>
|
|
195
|
+
<GaesupController />
|
|
196
|
+
|
|
197
|
+
{/* Import Rideable component inside and pass the arguments as shown below */}
|
|
198
|
+
<Rideable
|
|
199
|
+
objectkey="1"
|
|
200
|
+
objectType="vehicle"
|
|
201
|
+
isRiderOn={true}
|
|
202
|
+
url={VEHICLE_URL}
|
|
203
|
+
wheelUrl={WHEEL_URL}
|
|
204
|
+
offset={V3(0, 0.5, 0)}
|
|
205
|
+
position={V3(-10, 5, 10)}
|
|
206
|
+
/>
|
|
207
|
+
<Rideable
|
|
208
|
+
objectkey="2"
|
|
209
|
+
objectType="vehicle"
|
|
210
|
+
isRiderOn={false}
|
|
211
|
+
url={VEHICLE_URL}
|
|
212
|
+
wheelUrl={WHEEL_URL}
|
|
213
|
+
position={V3(-20, 5, 10)}
|
|
214
|
+
/>
|
|
215
|
+
<Rideable
|
|
216
|
+
objectkey="3"
|
|
217
|
+
objectType="airplane"
|
|
218
|
+
isRiderOn={true}
|
|
219
|
+
url={AIRPLANE_URL}
|
|
220
|
+
offset={V3(0, 0.5, 0)}
|
|
221
|
+
position={V3(10, 5, 10)}
|
|
222
|
+
/>
|
|
223
|
+
<Rideable
|
|
224
|
+
objectkey="4"
|
|
225
|
+
objectType="airplane"
|
|
226
|
+
isRiderOn={false}
|
|
227
|
+
url={AIRPLANE_URL}
|
|
228
|
+
position={V3(20, 5, 10)}
|
|
229
|
+
/>
|
|
230
|
+
</Physics>
|
|
231
|
+
</Canvas>
|
|
232
|
+
</GaesupWorld>
|
|
233
|
+
);
|
|
234
|
+
}
|
|
235
|
+
```
|
|
236
|
+
|
|
237
|
+
### 2) Precautions
|
|
238
|
+
|
|
239
|
+
- The `objectkey` must be unique.
|
|
240
|
+
|
|
241
|
+
### 3) Props
|
|
242
|
+
|
|
243
|
+
| Prop Name | Type | Required | Description | Default Value |
|
|
244
|
+
| -------------- | ----------------------- | -------- | ----------------------------------------------- | -------------- |
|
|
245
|
+
| `objectkey` | string | Required | Unique identifier for the rideable object | None |
|
|
246
|
+
| `objectType` | "vehicle" or "airplane" | Optional | Type of the rideable object | `undefined` |
|
|
247
|
+
| `isRiderOn` | boolean | Optional | Whether a rider is on the rideable object | `false` |
|
|
248
|
+
| `url` | string | Optional | 3D model URL for the rideable object | `null` |
|
|
249
|
+
| `wheelUrl` | string | Optional | Wheel model URL for "vehicle" type rideables | `null` |
|
|
250
|
+
| `position` | THREE.Vector3 | Optional | Initial position of the rideable object | `(0, 0, 0)` |
|
|
251
|
+
| `rotation` | THREE.Euler | Optional | Initial rotation angle of the rideable object | `(0, 0, 0)` |
|
|
252
|
+
| `offset` | THREE.Vector3 | Optional | Initial position offset for the rideable object | `(0, 0, 0)` |
|
|
253
|
+
| `visible` | boolean | Optional | Visibility of the rideable object | `true` |
|
|
254
|
+
| `vehicleSize` | THREE.Vector3 | Optional | Size of the "vehicle" type rideable object | Rapier default |
|
|
255
|
+
| `wheelSize` | THREE.Vector3 | Optional | Size of the wheel for "vehicle" type rideables | Rapier default |
|
|
256
|
+
| `airplaneSize` | THREE.Vector3 | Optional | Size of the "airplane" type rideable object | Rapier default |
|
|
257
|
+
|
|
258
|
+
### 4) Features
|
|
259
|
+
|
|
260
|
+
1. **Support for Various Rideable Objects:** The Rideable component can render a variety of rideable objects, including "vehicle" and "airplane" types. It can render the 3D models of each object and allow interactions with them.
|
|
261
|
+
2. **Customizable Properties:** You can easily configure the initial state, size, model URLs, visibility, and more of rideable objects using component properties.
|
|
262
|
+
3. **Interaction with Riders:** The Rideable component supports interactions required for a rider to board and move with rideable objects.
|
|
263
|
+
|
|
264
|
+
### 5) Advantages
|
|
265
|
+
|
|
266
|
+
- **Modularity and Reusability:** The Rideable component is modular and can be easily integrated with other components, increasing code reusability and facilitating maintenance.
|
|
267
|
+
|
|
268
|
+
- **Rapid Development:** By using the `useRideable` hook, which manages the physics engine and rideable object management, developers can quickly implement and render rideable objects, reducing development time.
|
|
269
|
+
|
|
270
|
+
- **Real-time Interaction:** Leveraging the Rapier physics engine allows for real-time handling of rideable object movements and collision checks, providing a high level of interaction in games or simulations.
|
|
271
|
+
|
|
272
|
+
- **Flexible Customization:** You can customize the appearance and behavior of each rideable object using properties, making it suitable for various game or simulation environments.
|
|
273
|
+
|
|
274
|
+
# Passive
|
|
275
|
+
|
|
276
|
+
---
|
|
277
|
+
|
|
278
|
+
under construct
|
|
279
|
+
|
|
280
|
+
# GaeSupProps
|
|
281
|
+
|
|
282
|
+
---
|
|
283
|
+
|
|
284
|
+
The `GaeSupProps` component is a React component used in a 3D environment. It is designed to represent various types of props or objects within the scene. This component can be used to create props with different types, text labels, and positions for visualization in a 3D space.
|
|
285
|
+
|
|
286
|
+
### (1) props
|
|
287
|
+
|
|
288
|
+
The `GaeSupProps` component accepts the following props:
|
|
289
|
+
|
|
290
|
+
- `type` (optional): A string specifying the type of the prop. It can be either `"normal"` or `"ground"`. Defaults to `"normal"` if not provided.
|
|
291
|
+
- `text` (optional): A string representing the text label associated with the prop. This label can provide additional information about the prop. If not provided, no label will be displayed.
|
|
292
|
+
- `position` (optional): An array of three numbers `[x, y, z]` specifying the initial position of the prop in the 3D space. If not provided, the prop will be positioned at the origin `[0, 0, 0]`.
|
|
293
|
+
- `children` (required): This prop should contain the 3D content that makes up the visual representation of the prop. It can include any 3D objects or components you want to render within the prop.
|
|
294
|
+
|
|
295
|
+
### (2) example
|
|
296
|
+
|
|
297
|
+
- To use the `GaeSupProps` component, you need to import it and include it in your React component tree. Here's an example of how to use it:
|
|
298
|
+
|
|
299
|
+
```tsx
|
|
300
|
+
import { GaeSupProps } from "./GaeSupProps";
|
|
301
|
+
|
|
302
|
+
function MyScene() {
|
|
303
|
+
return (
|
|
304
|
+
<GaeSupProps type="normal" text="My Prop" position={[3, 1, -2]}>
|
|
305
|
+
{/* 3D content goes here */}
|
|
306
|
+
</GaeSupProps>
|
|
307
|
+
);
|
|
308
|
+
}
|
|
309
|
+
```
|
|
310
|
+
|
|
311
|
+
- In this example, we've created a `GaeSupProps` component with a `"normal"` type, a text label of `"My Prop"`, and a specific position in 3D space.
|
|
312
|
+
|
|
313
|
+
### (3) Behavior
|
|
314
|
+
|
|
315
|
+
- The `GaeSupProps` component also calculates the size and center of the 3D content it contains. It then updates a `minimap` object with this information, which can be useful for tracking the props within the scene.
|
|
316
|
+
|
|
317
|
+
- Additionally, the component uses the `useEffect` hook to dispatch updates to the context, ensuring that changes to the `minimap` object are reflected in the sce
|
|
318
|
+
|
|
319
|
+
# Tools
|
|
320
|
+
|
|
321
|
+
- Various tools that assist with character control in GaesupWorld
|
|
322
|
+
|
|
323
|
+
## GameBoy
|
|
324
|
+
|
|
325
|
+
- The GameBoy component is a controller interface that emulates GameBoy-like directional buttons. It is primarily intended for mobile usage.
|
|
326
|
+
|
|
327
|
+
### (1) props
|
|
328
|
+
|
|
329
|
+
| Prop Name | Type | Required | Description | Default Value |
|
|
330
|
+
| -------------------- | --------------- | -------- | ------------------------------------ | ------------- |
|
|
331
|
+
| `gamePadStyle` | object (styles) | Optional | Style for the GamePad container | `undefined` |
|
|
332
|
+
| `gamePadButtonStyle` | object (styles) | Optional | Style for individual GamePad buttons | `undefined` |
|
|
333
|
+
| `label` | string | Optional | Custom label for the buttons | `undefined` |
|
|
334
|
+
|
|
335
|
+
### (2) example
|
|
336
|
+
|
|
337
|
+
```tsx
|
|
338
|
+
import { GameBoy } from "./GameBoy";
|
|
339
|
+
import { GaesupWorldContext } from "../../world/context";
|
|
340
|
+
|
|
341
|
+
const App = () => {
|
|
342
|
+
return (
|
|
343
|
+
<GaesupWorld>
|
|
344
|
+
{/* ... */}
|
|
345
|
+
<GameBoy
|
|
346
|
+
gameboyStyle={gameboyStyle}
|
|
347
|
+
gameboyButtonStyle={gameboyButtonStyle}
|
|
348
|
+
/>
|
|
349
|
+
{/* ... */}
|
|
350
|
+
</GaesupWorld>
|
|
351
|
+
);
|
|
352
|
+
};
|
|
353
|
+
```
|
|
354
|
+
|
|
355
|
+
### (3) Key Features:
|
|
356
|
+
|
|
357
|
+
- **Direction Buttons:** Implements buttons for directional input (forward, backward, left, right) based on the `GameBoyDirections` array.
|
|
358
|
+
- **Context-aware Rendering:** Renders the component based on the `mode.controller` value from the `GaesupWorldContext`.
|
|
359
|
+
- **Custom Styling:** Provides `gameboyStyle` and `gameboyButtonStyle` properties for styling customization.
|
|
360
|
+
|
|
361
|
+
### (4) How to Use
|
|
362
|
+
|
|
363
|
+
To use the `GameBoy` component:
|
|
364
|
+
|
|
365
|
+
1. Place the `GameBoy` component within your component tree.
|
|
366
|
+
2. Customize the appearance by defining styles in the `gameboyStyle` and `gameboyButtonStyle` properties.
|
|
367
|
+
3. The component renders buttons based on the `GameBoyDirections` array.
|
|
368
|
+
|
|
369
|
+
## GamePad
|
|
370
|
+
|
|
371
|
+
- The GamePad component provides a customizable controller interface that supports various controller modes, such as joysticks and GameBoys, making it versatile for different input scenarios.
|
|
372
|
+
|
|
373
|
+
### (1) props
|
|
374
|
+
|
|
375
|
+
| Prop Name | Type | Required | Description | Default Value |
|
|
376
|
+
| -------------------- | --------------- | -------- | ------------------------------------ | ------------- |
|
|
377
|
+
| `gamePadStyle` | object (styles) | Optional | Style for the GamePad container | `undefined` |
|
|
378
|
+
| `gamePadButtonStyle` | object (styles) | Optional | Style for individual GamePad buttons | `undefined` |
|
|
379
|
+
| `label` | string | Optional | Custom label for the buttons | `undefined` |
|
|
380
|
+
|
|
381
|
+
### (2) example
|
|
382
|
+
|
|
383
|
+
```tsx
|
|
384
|
+
import { GamePad } from "./GamePad";
|
|
385
|
+
import { GaesupWorldContext } from "../../world/context";
|
|
386
|
+
|
|
387
|
+
const App = () => {
|
|
388
|
+
return (
|
|
389
|
+
<GaesupWorld>
|
|
390
|
+
{/* ... */}
|
|
391
|
+
<GamePad
|
|
392
|
+
gamePadStyle={gamePadStyle}
|
|
393
|
+
gamePadButtonStyle={gamePadButtonStyle}
|
|
394
|
+
/>
|
|
395
|
+
{/* ... */}
|
|
396
|
+
</GaesupWorld>
|
|
397
|
+
);
|
|
398
|
+
};
|
|
399
|
+
```
|
|
400
|
+
|
|
401
|
+
### (3) Key Features
|
|
402
|
+
|
|
403
|
+
- **Dynamic Button Rendering:** Dynamically generates buttons based on the `control` object in the `GaesupWorldContext`.
|
|
404
|
+
- **Universal Usage:** Compatible with various controller modes like joysticks and GameBoys.
|
|
405
|
+
- **Custom Styling:** Allows customization of the GamePad's appearance using the `gamePadStyle` and `gamePadButtonStyle` properties.
|
|
406
|
+
|
|
407
|
+
### (4) How to Use
|
|
408
|
+
|
|
409
|
+
1. Include the `GamePad` component within your component tree.
|
|
410
|
+
2. Customize the appearance using the `gamePadStyle` and `gamePadButtonStyle` properties.
|
|
411
|
+
3. The component dynamically renders buttons based on the `control` mode.
|
|
412
|
+
|
|
413
|
+
## joystick
|
|
414
|
+
|
|
415
|
+
---
|
|
416
|
+
|
|
417
|
+
- The joystick component provides a virtual joystick interface, primarily intended for mobile environments. This component allows you to simulate joystick-like input on mobile devices. Additionally, you can prevent position jitter, which can occur on mobile devices, by using the `scrollBlock` option in the `GaesupWorld` component.
|
|
418
|
+
|
|
419
|
+
### (1) props
|
|
420
|
+
|
|
421
|
+
| Prop Name | Type | Required | Description | Default Value |
|
|
422
|
+
| ------------------- | --------------- | -------- | --------------------------- | ------------- |
|
|
423
|
+
| `joystickStyle` | object (styles) | Optional | Style for the joystick | `undefined` |
|
|
424
|
+
| `joystickBallStyle` | object (styles) | Optional | Style for the joystick ball | `undefined` |
|
|
425
|
+
|
|
426
|
+
### (2) example
|
|
427
|
+
|
|
428
|
+
```jsx
|
|
429
|
+
const MyComponent = () => {
|
|
430
|
+
const joystickStyle = {
|
|
431
|
+
/* joystickStyle */
|
|
432
|
+
};
|
|
433
|
+
const joystickBallStyle = {
|
|
434
|
+
/* joystickBallStyle */
|
|
435
|
+
};
|
|
436
|
+
|
|
437
|
+
return (
|
|
438
|
+
<GaesupWorld>
|
|
439
|
+
{/* ... */}
|
|
440
|
+
<joystick
|
|
441
|
+
joystickStyle={joystickStyle}
|
|
442
|
+
joystickBallStyle={joystickBallStyle}
|
|
443
|
+
/>
|
|
444
|
+
{/* ... */}
|
|
445
|
+
</GaesupWorld>
|
|
446
|
+
);
|
|
447
|
+
};
|
|
448
|
+
```
|
|
449
|
+
|
|
450
|
+
### (3) Key Features:
|
|
451
|
+
|
|
452
|
+
- **joystick Interface:** Provides a joystick-like user input interface, suitable for mobile devices.
|
|
453
|
+
- **Customization:** You can customize the style of the joystick component by adjusting the styles of the joystick and the joystick ball using the `joystickBallStyle` and `joystickStyle` properties.
|
|
454
|
+
- **Responsive and Interactive:** It supports various input devices and responds to both mouse and mobile touch events for controlling movement.
|
|
455
|
+
|
|
456
|
+
## 4) JumpPortal
|
|
457
|
+
|
|
458
|
+
- The `JumpPortal` component represents a clickable portal that allows users to teleport to a specified location within a 3D world. This component can be used to create interactive teleportation points in your application.
|
|
459
|
+
|
|
460
|
+
### (1) props
|
|
461
|
+
|
|
462
|
+
| Prop Name | Type | Required | Description | Default Value |
|
|
463
|
+
| ----------------- | ------------- | -------- | ----------------------------------------------------------- | ------------- |
|
|
464
|
+
| `text` | string | Optional | The text to display on the portal. | `undefined` |
|
|
465
|
+
| `position` | THREE.Vector3 | Required | The target position to teleport to using a `THREE.Vector3`. | None |
|
|
466
|
+
| `jumpPortalStyle` | CSSProperties | Optional | CSS styles for customizing the appearance of the portal. | `undefined` |
|
|
467
|
+
|
|
468
|
+
### (2) example
|
|
469
|
+
|
|
470
|
+
- To use the `JumpPortal` component, you can import it and include it in your React application as follows:
|
|
471
|
+
|
|
472
|
+
```tsx
|
|
473
|
+
import { JumpPortal } from "./JumpPortal";
|
|
474
|
+
import * as THREE from "three";
|
|
475
|
+
|
|
476
|
+
const App = () => {
|
|
477
|
+
return (
|
|
478
|
+
<GaesupWorld>
|
|
479
|
+
{/* ... */}
|
|
480
|
+
<JumpPortal
|
|
481
|
+
text="Teleport"
|
|
482
|
+
position={new THREE.Vector3(10, 0, 5)}
|
|
483
|
+
jumpPortalStyle={{ backgroundColor: "blue", color: "white" }}
|
|
484
|
+
/>
|
|
485
|
+
{/* ... */}
|
|
486
|
+
</GaesupWorld>
|
|
487
|
+
);
|
|
488
|
+
};
|
|
489
|
+
```
|
|
490
|
+
|
|
491
|
+
## KeyBoardToolTip
|
|
492
|
+
|
|
493
|
+
---
|
|
494
|
+
|
|
495
|
+
- The KeyBoardToolTip component is designed to visually represent a keyboard controller interface, providing a visual representation of each key and its associated action.
|
|
496
|
+
|
|
497
|
+
### Key Features
|
|
498
|
+
|
|
499
|
+
- **Visualizing Keyboard Keys:** Visualizes all keyboard keys in an array format.
|
|
500
|
+
- **State Animation:** Reflects the currently active keys and their associated actions by displaying them differently to provide user feedback.
|
|
501
|
+
- **Custom Styling:** Provides various styling properties for customizing key caps' appearance.
|
|
502
|
+
|
|
503
|
+
### How to Use
|
|
504
|
+
|
|
505
|
+
1. Include the `KeyBoardToolTip` component within the `GaesupWorld` component.
|
|
506
|
+
2. Define the `control` mode as "keyboard" in the `mode` property.
|
|
507
|
+
3. The component visualizes each keyboard key based on the `KeyBoardAll` constant and applies different styles for currently active keys.
|
|
508
|
+
4. (Optional) Customize the styles using the `keyBoardToolTipInnerStyle`, `selectedKeyCapStyle`, `notSelectedkeyCapStyle`, and `keyCapStyle` properties.
|
|
509
|
+
|
|
510
|
+
### Example:
|
|
511
|
+
|
|
512
|
+
```tsx
|
|
513
|
+
import { KeyBoardToolTip } from "./KeyBoardToolTip";
|
|
514
|
+
import { GaesupWorldContext } from "../../world/context";
|
|
515
|
+
|
|
516
|
+
const App = () => {
|
|
517
|
+
return (
|
|
518
|
+
<GaesupWorld>
|
|
519
|
+
{/* ... */}
|
|
520
|
+
<KeyBoardToolTip
|
|
521
|
+
keyBoardToolTipInnerStyle={keyBoardToolTipInnerStyle}
|
|
522
|
+
selectedKeyCapStyle={selectedKeyCapStyle}
|
|
523
|
+
notSelectedkeyCapStyle={notSelectedkeyCapStyle}
|
|
524
|
+
keyCapStyle={keyCapStyle}
|
|
525
|
+
/>
|
|
526
|
+
{/* ... */}
|
|
527
|
+
</GaesupWorld>
|
|
528
|
+
);
|
|
529
|
+
};
|
|
530
|
+
```
|
|
531
|
+
|
|
532
|
+
## MiniMap
|
|
533
|
+
|
|
534
|
+
---
|
|
535
|
+
|
|
536
|
+
- The MiniMap component is used to display a small map of the user's location and the surrounding environment within a 3D world.
|
|
537
|
+
|
|
538
|
+
### (1) props
|
|
539
|
+
|
|
540
|
+
| Prop Name | Type | Required | Description | Default Value |
|
|
541
|
+
| ---------------- | --------------- | -------- | --------------------------------------------- | ------------- |
|
|
542
|
+
| `innerStyle` | object (styles) | Optional | Style for the inner MiniMap container | `undefined` |
|
|
543
|
+
| `textStyle` | object (styles) | Optional | Style for text within the MiniMap | `undefined` |
|
|
544
|
+
| `objectStyle` | object (styles) | Optional | Style for objects within the MiniMap | `undefined` |
|
|
545
|
+
| `avatarStyle` | object (styles) | Optional | Style for avatars within the MiniMap | `undefined` |
|
|
546
|
+
| `scaleStyle` | object (styles) | Optional | Style for the scale control of the MiniMap | `undefined` |
|
|
547
|
+
| `directionStyle` | object (styles) | Optional | Style for direction indicators in the MiniMap | `undefined` |
|
|
548
|
+
| `plusMinusStyle` | object (styles) | Optional | Style for plus/minus controls in the MiniMap | `undefined` |
|
|
549
|
+
|
|
550
|
+
### 2) example
|
|
551
|
+
|
|
552
|
+
```tsx
|
|
553
|
+
import { MiniMap } from "./MiniMap";
|
|
554
|
+
|
|
555
|
+
const App = () => {
|
|
556
|
+
return (
|
|
557
|
+
<GaesupWorld>
|
|
558
|
+
{/* ... */}
|
|
559
|
+
<MiniMap
|
|
560
|
+
minimapStyle={minimapStyle}
|
|
561
|
+
innerStyle={innerStyle}
|
|
562
|
+
// Pass other style properties as needed
|
|
563
|
+
/>
|
|
564
|
+
{/* ... */}
|
|
565
|
+
</GaesupWorld>
|
|
566
|
+
);
|
|
567
|
+
};
|
|
568
|
+
```
|
|
569
|
+
|
|
570
|
+
### 3) Key Features
|
|
571
|
+
|
|
572
|
+
- **Dynamic Scaling:** Allows users to dynamically adjust the size of the map.
|
|
573
|
+
- **Direction Indicators:** Visualizes directions such as East, West, South, and North.
|
|
574
|
+
- **Custom Styling:** Allows customization of the MiniMap and its internal elements.
|
|
575
|
+
- **Mouse Wheel Support:** Supports adjusting the map's scale using the mouse wheel.
|
|
576
|
+
|
|
577
|
+
### 4) How to Use
|
|
578
|
+
|
|
579
|
+
1. Include the `MiniMap` component within your component tree.
|
|
580
|
+
2. Customize the appearance using the `minimapStyle`, `innerStyle`, `textStyle`, `objectStyle`, `avatarStyle`, `scaleStyle`, `directionStyle`, and `plusMinusStyle` properties as needed.
|
|
581
|
+
3. The component updates the MiniMap based on the user's current position and direction.
|
|
582
|
+
|
|
583
|
+
## ZoomButton
|
|
584
|
+
|
|
585
|
+
---
|
|
586
|
+
|
|
587
|
+
- The ZoomButton component is used to move the camera to a specific location and control the camera's zoom, primarily used for zooming to a target.
|
|
588
|
+
|
|
589
|
+
### (1) props
|
|
590
|
+
|
|
591
|
+
| Prop Name | Type | Required | Description | Default Value |
|
|
592
|
+
| ----------------- | --------------- | -------- | ---------------------------------------------------------- | ------------- |
|
|
593
|
+
| `position` | THREE.Vector3 | Required | Target position for the camera to move to | None |
|
|
594
|
+
| `children` | React.ReactNode | Optional | React nodes to render within the button | `undefined` |
|
|
595
|
+
| `target` | THREE.Vector3 | Optional | Target position for the camera to look at | `undefined` |
|
|
596
|
+
| `keepBlocking` | boolean | Optional | Determines whether to keep blocking while camera is moving | `undefined` |
|
|
597
|
+
| `zoomButtonStyle` | object (styles) | Optional | Style for the ZoomButton component | `undefined` |
|
|
598
|
+
|
|
599
|
+
### (2) example
|
|
600
|
+
|
|
601
|
+
```tsx
|
|
602
|
+
import { ZoomButton } from "./ZoomButton";
|
|
603
|
+
import * as THREE from "three";
|
|
604
|
+
|
|
605
|
+
const App = () => {
|
|
606
|
+
return (
|
|
607
|
+
<GaesupWorld>
|
|
608
|
+
{/* ... */}
|
|
609
|
+
<ZoomButton position={new THREE.Vector3(0, 0, 5)}>{childern}</ZoomButton>
|
|
610
|
+
{/* ... */}
|
|
611
|
+
</GaesupWorld>
|
|
612
|
+
);
|
|
613
|
+
};
|
|
614
|
+
```
|
|
615
|
+
|
|
616
|
+
### (3) How to Use
|
|
617
|
+
|
|
618
|
+
1. Place the `ZoomButton` component in your component tree at the desired location.
|
|
619
|
+
2. Define the `position` prop to specify the location the camera should move to.
|
|
620
|
+
3. When the button is clicked, the camera will move to the specified position.
|