feat:上传mcguide-开发指南部份
This commit is contained in:
Othniel su
266
mcguide/20-玩法开发/10-基本概念/1-我的世界基础概念.md
Normal file
266
mcguide/20-玩法开发/10-基本概念/1-我的世界基础概念.md
Normal file
@@ -0,0 +1,266 @@
|
||||
---
|
||||
front:
|
||||
hard: 入门
|
||||
time: 分钟
|
||||
---
|
||||
|
||||
# <span id="我的世界基础概念"></span>我的世界基础概念
|
||||
|
||||
<span id='世界'></span>
|
||||
|
||||
## 世界
|
||||
|
||||
表示游戏的单位，单个游戏存档、单个网络服务器等都是一个世界。
|
||||
|
||||
<span id='区块'></span>
|
||||
|
||||
## 区块
|
||||
|
||||
区块是世界里一个大小为16×384×16的部分，是游戏地图加载卸载的基本单位。
|
||||
|
||||
当玩家第一次出现在世界时会在其周围生成区块，随着玩家对世界的探索，相邻的区块也会被生成。
|
||||
|
||||
区块的X坐标：Floor(X坐标 / 16)，区块的Z坐标：Floor(Z坐标 / 16)，Floor意为向下取整。
|
||||
|
||||
一个区块(X, Z)中坐标最小点的坐标为(X * 16, -64, Z * 16)，坐标最大点的坐标为(X * 16 + 15, 320, Z * 16 + 15)。
|
||||
|
||||
<span id='实体'></span>
|
||||
|
||||
## 实体
|
||||
|
||||
具有可区别性的物体，不一定是物理存在的实体。
|
||||
|
||||
包括服务端运算的，会保存到存档的生物实体、物品实体、方块实体、抛射物实体等
|
||||
|
||||
以及纯客户端表现，退出游戏后就销毁的特效实体（粒子实体、序列帧实体）、文字面板实体等。
|
||||
|
||||
<span id='生物'></span>
|
||||
## 生物
|
||||
|
||||
指游戏世界中有生命的，可移动的一类实体。其中玩家也属于生物的一种。
|
||||
|
||||
<span id='玩家'></span>
|
||||
## 玩家
|
||||
|
||||
玩家所控制的实体对象，同时也属于生物的一种。包括本地玩家和其他玩家，在游戏中，由玩家自己控制的称为本地玩家，否则为其他玩家。
|
||||
|
||||
<span id='物品'></span>
|
||||
## 物品
|
||||
|
||||
物品栏中具有使用属性的物品、地面上的掉落物等都称为物品。其中掉落物也是实体的一种。
|
||||
|
||||
|
||||
<span id='附魔信息字典'></span>
|
||||
## 附魔信息字典
|
||||
|
||||
该字典的内容如下
|
||||
|
||||
| 关键字 | 数据类型 | 说明 |
|
||||
| ---------------- | --------- | ---- |
|
||||
| identifier | str | 自定义附魔id|
|
||||
| description | str | 对于zh_CN.lang中的langStr |
|
||||
| primary_slots | list[str] | 附魔槽位，详见自定义附魔<a href="../15-自定义游戏内容/11-自定义附魔文档.html">自定义附魔</a> |
|
||||
| cost | list[int] | 附魔威力等级对应的经验消耗，会影响砂轮移除魔咒时返回的经验值以及在附魔台上被附魔到该魔咒的概率（cost越大附魔概率越小）;列表内元素数量需与max_level一致，否则注册失败 |
|
||||
| frequency | str | 附魔稀有度，影响铁砧结合附魔物品的经验消耗，默认为common，详见自定义附魔<a href="../15-自定义游戏内容/11-自定义附魔文档.html">自定义附魔</a>|
|
||||
| is_treasure_only | bool | 设为true时为宝藏型魔咒，将影响附魔获取方式，默认为false |
|
||||
| is_discoverable | bool | 设为false时为宝藏型魔咒，将影响附魔获取方式，默认为true |
|
||||
| is_lootable | bool | 设为true时可以通过与图书管理员交易获得，默认为true |
|
||||
| is_curse | bool | 设为true时为诅咒附魔，不可通过砂轮移除，默认为false |
|
||||
| max_level | int | 附魔威力等级，设置后会自动在创造物品栏注册各等级的附魔书，默认为1 |
|
||||
| incompatible | list[str] | ["unbreaking"] // 冲突附魔名称 |
|
||||
|
||||
<span id='物品信息字典'></span>
|
||||
## 物品信息字典
|
||||
|
||||
也叫itemDict。是python事件与接口中获取物品信息以及生成物品时使用的dict类型的变量。
|
||||
|
||||
该字典的内容如下
|
||||
|
||||
| 关键字 | 数据类型 | 说明 |
|
||||
| -------------- | ----------------------------- | ------------------------------------------------------------ |
|
||||
| newItemName | str | 必须设置，物品的identifier，即"命名空间:物品名" |
|
||||
| newAuxValue | int | 必须设置，物品附加值 |
|
||||
| itemName | str | （废弃）1.22及以前版本的旧identifier，详见<a href="../13-模组SDK编程/2-Python脚本开发/99-1.23版本物品id变更.html">1.23版本物品id变更</a> |
|
||||
| auxValue | int | （废弃）1.22及以前版本的旧物品附加值，详见<a href="../13-模组SDK编程/2-Python脚本开发/99-1.23版本物品id变更.html">1.23版本物品id变更</a> |
|
||||
| count | int | 必须设置，物品数量。设置为0时为空物品 |
|
||||
| showInHand | bool | 可选，是否显示在手上，默认为True |
|
||||
| enchantData | list(tuple(EnchantType, int)) | 可选，附魔数据，tuple中<a href="../../../mcdocs/1-ModAPI/枚举值/EnchantType.html" rel="noopenner"> EnchantType </a>为附魔类型，int为附魔等级 |
|
||||
| modEnchantData | list(tuple(str, int)) | 可选，自定义附魔数据，tuple中str为自定义附魔id，int为自定义附魔等级 |
|
||||
| customTips | str | 可选，物品的自定义tips，修改该内容后会覆盖实例的组件<a href="../15-自定义游戏内容/1-自定义物品/1-自定义基础物品.html">netease:customtips</a>的内容 |
|
||||
| extraId | str | 可选，物品自定义标识符。可以用于保存数据， 区分物品 |
|
||||
| userData | dict | 可选，物品userData，用于灾厄旗帜、旗帜等物品，请勿随意设置该值 |
|
||||
| durability | int | 可选，物品耐久度，不存在耐久概念的物品默认值为零 |
|
||||
|
||||
|
||||
|
||||
customTips 设置支持自定义格式：包含四种自带格式：
|
||||
|
||||
| 格式字符串 | 说明 |
|
||||
| --------------- | -------- |
|
||||
| %name% | 物品名 |
|
||||
| %category% | 物品类型 |
|
||||
| %enchanting% | 附魔属性 |
|
||||
| %attack_damage% | 攻击伤害 |
|
||||
|
||||
自带格式可以与自定义文本自由组合，顺序可以打乱，物品的自定义格式的文本不存在时不予显示。
|
||||
|
||||
自带格式的字符串采用原版的显示格式，物品名前面不带换行符，物品类型、附魔属性前面自带一个换行符，攻击伤害前面自带两个换行符。
|
||||
|
||||
举个例子：`head%name%after%category%%enchanting%\nnewline%attack_damage%\n\nend`，效果如下：
|
||||
|
||||
|
||||
|
||||
|
||||
<span id='记分板记分准则信息字典'></span>
|
||||
|
||||
## 记分板记分准则信息字典
|
||||
也叫scoreDict。是python事件与接口中获取的记分准则及其分数
|
||||
|
||||
该字典的内容如下
|
||||
|
||||
| 关键字 | 数据类型 | 说明 |
|
||||
| ------ | -------- | ------------------------------------------------------------ |
|
||||
| displayName | str | 记分项显示名称 |
|
||||
| name | str | 记分项名称 |
|
||||
| criteriaName | str | 记分准则类型名称，目前基岩版只支持(dummy) ，只有获取所有记分项数据时才会有该字段 |
|
||||
| value | int | 玩家分数(只有获取玩家分数接口时会有该字段) |
|
||||
|
||||
* 记分板相关释义详见 [官方wiki](https://zh.minecraft.wiki/w/%E8%AE%B0%E5%88%86%E6%9D%BF)
|
||||
|
||||
<span id='玩家记分项信息字典'></span>
|
||||
|
||||
## 玩家记分项信息字典
|
||||
|
||||
也叫playerScoreDict。是python事件与接口中获取单个玩家所有的记分准则及其分数
|
||||
|
||||
该字典的内容如下
|
||||
|
||||
| 关键字 | 数据类型 | 说明 |
|
||||
| ------ | -------- | ------------------------------------------------------------ |
|
||||
| playerId | str | 玩家id |
|
||||
| scoreList | list(scoreDict) | 记分准则及分数列表 |
|
||||
|
||||
* 记分板相关释义详见 [官方wiki](https://zh.minecraft.wiki/w/%E8%AE%B0%E5%88%86%E6%9D%BF)
|
||||
|
||||
<span id='方块'></span>
|
||||
|
||||
## 方块
|
||||
|
||||
游戏中场景的基本组成单位，长宽高均为1单位长度的立方体网格，不同的方块具有不同的材质。
|
||||
|
||||
<span id='方块信息字典'></span>
|
||||
|
||||
## 方块信息字典
|
||||
|
||||
也叫blockDict。是python事件与接口中获取方块信息以及生成方块时使用的dict类型的变量。
|
||||
|
||||
该字典的内容如下
|
||||
|
||||
| 关键字 | 数据类型 | 说明 |
|
||||
| ------ | -------- | ------------------------------------------------------------ |
|
||||
| name | str | 必须设置，方块identifier，包含命名空间及名称，如minecraft:air |
|
||||
| aux | int | 方块附加值，可缺省，默认为0 |
|
||||
|
||||
* 原版方块的identifier可以查看[官方wiki](https://minecraft-zh.gamepedia.com/基岩版数据值)
|
||||
|
||||
<span id='方块状态'></span>
|
||||
|
||||
## 方块状态
|
||||
|
||||
一种方块可能存在多种方块状态，例如不同颜色的羊毛。一个auxvalue实际上也是对应一种方块状态，只是相比于用int来表示的auxvalue，方块状态更为可读。
|
||||
|
||||
例如，橙色羊毛的identifier为minecraft:wool，auxvalue为1，而用方块状态则表示为：
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "minecraft:wool",
|
||||
"states": {
|
||||
"color": "orange"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
可以在游戏内使用GetBlockStates将方块状态打印出来。
|
||||
|
||||
也可以在[Block_states页面](https://minecraft.gamepedia.com/Block_states)中查阅，一些没有的可以在方块的页面找到，例如[羊毛](https://minecraft.gamepedia.com/Wool#Block_states)与[泥土](https://minecraft.gamepedia.com/Dirt#Block_states)。注意要使用基岩版及Bedrock Edition里的内容。（不排除wiki上有遗漏或错误）
|
||||
|
||||
<span id='方块基本信息字典'></span>
|
||||
|
||||
## 方块基本信息字典
|
||||
也叫blockBasicDict。是python事件与接口中获取方块基本信息时使用的dict类型的变量。
|
||||
|
||||
该字典的内容如下
|
||||
|
||||
| 关键字 | 数据类型 | 说明 |
|
||||
| ------ | -------- | ------------------------------------------------------------ |
|
||||
| blockLightAbsorption | int | 方块透光率, 具体见[官方wiki](https://zh.minecraft.wiki/w/%E4%BA%AE%E5%BA%A6)
|
||||
| blockLightEmission | int | 方块亮度, 具体见[官方wiki](https://zh.minecraft.wiki/w/%E4%BA%AE%E5%BA%A6)|
|
||||
| breathability | int | 方块的<a href="../../../mcdocs/1-ModAPI/枚举值/BlockBreathability.html" rel="noopenner"> 可呼吸性 </a>(只有定义了"minecraft:breathability"组件的方块有数据,其余默认为solid的枚举值)(需要开启假日创造者功能)|
|
||||
| explosionResistance | float | 方块爆炸抗性|
|
||||
| loot | str | loot table控制掉落物(只有定义了"minecraft:loot"组件的方块有数据,其余默认为空字符串"")|
|
||||
| mapColor | str | 用十六进制颜色定义该方块在地图上显示的颜色(只有定义了"minecraft:map_color"组件的方块以及部分原版方块有数据,其余默认为"#0")|
|
||||
| unwalkable | bool | 生物是否可在上方行走,默认为false(只有定义了"<a href="../../../mconline/100-历史归档教程/20-玩法地图教程/第07章：使用实验玩法增加自定义内容/课程01.接触新自定义方块.html#minecraft-unwalkable">minecraft:unwalkable</a>"组件的方块有数据,其余默认为false)|
|
||||
| tier | dict/None | 与挖掘相关的属性,具体见<a href="../../20-玩法开发/15-自定义游戏内容/2-自定义方块/1-JSON组件.html">挖掘属性</a>(只有定义了"netease:tier"组件的方块有数据,其余默认为None)|
|
||||
| renderLayer | int | 方块渲染时使用的<a href="../../../mcdocs/1-ModAPI/枚举值/RenderLayer.html" rel="noopenner"> 材质 </a>|
|
||||
| solid | bool | 方块是否为实心方块,影响生物在方块内是否受到窒息伤害|
|
||||
| pathable | bool | 游戏内AI在进行寻路时，方块是否被当作障碍物(只有定义了"netease:pathable"组件的方块有数据,其余默认为false)|
|
||||
| fireResistant | bool | 方块是否防火(只有定义了"netease:fire_resistant"组件的方块有数据,其余默认为false)|
|
||||
| creativeCategory | int | 方块所在<a href="../../../mcdocs/1-ModAPI/枚举值/ItemCategory.html" rel="noopenner"> 创造栏目录 </a>|
|
||||
| destroyTime | float | 方块摧毁时间|
|
||||
|
||||
<span id='NBT数据格式'></span>
|
||||
## NBT数据格式
|
||||
原版方块实体数据、物品userData使用[NBT格式](https://zh.minecraft.wiki/w/NBT%E6%A0%BC%E5%BC%8F)存取，再通过Python接口获取时，会进行一定的转换，具体转换规则如下：
|
||||
|
||||
| NBT类型 | 转换后Python数据 |
|
||||
| ------ | -------- |
|
||||
|Byte | {"\_\_type\_\_" : 1, "_\_\_value\_\_": True/False} |
|
||||
|Short | {"\_\_type\_\_" : 2, "_\_\_value\_\_": ShortValue} |
|
||||
|Int | {"\_\_type\_\_" : 3, "\_\_value\_\_": IntValue} |
|
||||
|Int64 | {"\_\_type\_\_" : 4, "\_\_value\_\_": Int64Value} |
|
||||
|Float | {"\_\_type\_\_" : 5, "\_\_value\_\_": FloatValue} |
|
||||
|Double | {"\_\_type\_\_" : 6, "\_\_value\_\_": DoubleValue} |
|
||||
|ByteArray | {"\_\_type\_\_" : 7, "\_\_value\_\_": IntList} |
|
||||
|String | {"\_\_type\_\_" : 8, "\_\_value\_\_": String} |
|
||||
|List | {"\_\_type\_\_" : 9, "\_\_value\_\_": ...(递归转换)} |
|
||||
|Compound | {"\_\_type\_\_" : 10, "\_\_value\_\_": ...(递归转换)} |
|
||||
|IntArray | {"\_\_type\_\_" : 11, "\_\_value\_\_": IntList} |
|
||||
|
||||
<span id='抛射物'></span>
|
||||
|
||||
## 抛射物
|
||||
|
||||
受外力被抛射空中飞行的实体，受重力与摩擦力影响，例如游戏中射出的箭。
|
||||
|
||||
<span id='生物群系'></span>
|
||||
## 生物群系
|
||||
|
||||
游戏中生成的世界被划分为一个个不同的自然环境，例如森林、丛林、沙漠和针叶林等，这些都是不同的生物群系。
|
||||
|
||||
<span id='模型'></span>
|
||||
## 骨骼模型
|
||||
|
||||
与基岩版原版的基于cube搭建的模型不同，是使用3dmax等建模软件搭建的模型。游戏中的大部分生物都可以被替换为骨骼模型，进而实现不同的表现效果。
|
||||
|
||||
<span id='序列帧'></span>
|
||||
## 序列帧
|
||||
|
||||
通过一帧帧的图片不断进行切换形成的动画效果，在游戏中为一个平面面片。
|
||||
|
||||
<span id='粒子'></span>
|
||||
## 粒子
|
||||
|
||||
通过不断发射多个不同大小规模的平面面片形成的特效效果，通过替换贴图材质等可以模拟丰富的表现。
|
||||
|
||||
<span id='文字面板'></span>
|
||||
|
||||
## 文字面板
|
||||
|
||||
本质上为序列帧的文字面板，功能上与文本类似，在游戏中包括伤害飘字，实体头顶名称等内容。
|
||||
|
||||
<span id='UI'></span>
|
||||
|
||||
## UI
|
||||
|
||||
UI界面，游戏和用户之间进行交互和信息交换的界面。玩家可以通过触发UI来控制对应的游戏逻辑。
|
||||
|
||||
554
mcguide/20-玩法开发/10-基本概念/10-Vector3.md
Normal file
554
mcguide/20-玩法开发/10-基本概念/10-Vector3.md
Normal file
@@ -0,0 +1,554 @@
|
||||
---
|
||||
front:
|
||||
hard: 入门
|
||||
time: 分钟
|
||||
---
|
||||
|
||||
# Vector3
|
||||
|
||||
- 描述
|
||||
|
||||
用于表示 3D 向量和点。
|
||||
|
||||
可以使用该结构保存与计算 3D 位置和方向。 此外，它还包含用于执行常见向量操作的函数。
|
||||
|
||||
MC中使用的是右手坐标系，如下图所示。后文中的上下前后左右均是以steve面向z轴正方向得出来的。MC中东西方向为X坐标轴，其中X轴正方向为东，X轴负方向为西；南北方向为Z坐标轴，其中Z轴正方向为南，Z轴负方向为北。即左西右东前南后北。
|
||||
|
||||
|
||||
|
||||
## 构造函数
|
||||
|
||||
### Vector3(x, y, z)
|
||||
|
||||
- 描述
|
||||
|
||||
用于构造一个向量或者3维点坐标。
|
||||
|
||||
- 参数
|
||||
|
||||
| 参数名 | 数据类型 | 说明 |
|
||||
| ------ | :------- | :---------- |
|
||||
| x | float | 向量的x分量 |
|
||||
| y | float | 向量的y分量 |
|
||||
| z | float | 向量的z分量 |
|
||||
|
||||
- 返回值
|
||||
|
||||
| 数据类型 | 说明 |
|
||||
| :------- | :------------------- |
|
||||
| Vector3 | 返回Vector3(x, y, z) |
|
||||
|
||||
- 示例
|
||||
|
||||
```python
|
||||
from common.utils.mcmath import Vector3
|
||||
newOne = Vector3(1, 2, 3)
|
||||
```
|
||||
|
||||
|
||||
|
||||
### Vector3(vecTuple)
|
||||
|
||||
- 描述
|
||||
|
||||
用于构造一个向量或者3维点坐标。
|
||||
|
||||
- 参数
|
||||
|
||||
| 参数名 | 数据类型 | 说明 |
|
||||
| -------- | :------------------------- | :----------------- |
|
||||
| vecTuple | tuple(float, float, float) | 长度为3的tuple数组 |
|
||||
|
||||
- 返回值
|
||||
|
||||
| 数据类型 | 说明 |
|
||||
| :------- | :------------------------------------------------- |
|
||||
| Vector3 | 返回Vector3(vecTuple[0], vecTuple[1], vecTuple[2]) |
|
||||
|
||||
- 示例
|
||||
|
||||
```python
|
||||
from common.utils.mcmath import Vector3
|
||||
import client.extraClientApi as clientApi
|
||||
comp = clientApi.CreateComponent(entityId, "Minecraft", "pos")
|
||||
entityFootPos = comp.GetFootPos() # 通过位置组件获取实体位置
|
||||
posVec = Vector3(entityFootPos) # 直接将该位置tuple转换成Vector3以便后续计算
|
||||
```
|
||||
|
||||
|
||||
|
||||
## 静态方法
|
||||
|
||||
可以直接通过Vector3.MethodName()调用的静态方法，无需创建实例。
|
||||
|
||||
### One
|
||||
|
||||
- 描述
|
||||
|
||||
用于编写 Vector3(1, 1, 1) 的简便方法。
|
||||
|
||||
- 返回值
|
||||
|
||||
| 数据类型 | 说明 |
|
||||
| :------- | :------------------- |
|
||||
| Vector3 | 返回Vector3(1, 1, 1) |
|
||||
|
||||
- 示例
|
||||
|
||||
```python
|
||||
from common.utils.mcmath import Vector3
|
||||
newOne = Vector3.One()
|
||||
```
|
||||
|
||||
|
||||
|
||||
### Up
|
||||
|
||||
- 描述
|
||||
|
||||
用于编写 Vector3(0, 1, 0) 的简便方法。
|
||||
|
||||
- 返回值
|
||||
|
||||
| 数据类型 | 说明 |
|
||||
| :------- | :------------------- |
|
||||
| Vector3 | 返回Vector3(0, 1, 0) |
|
||||
|
||||
- 示例
|
||||
|
||||
```python
|
||||
from common.utils.mcmath import Vector3
|
||||
newOne = Vector3.Up()
|
||||
```
|
||||
|
||||
|
||||
|
||||
### Down
|
||||
|
||||
- 描述
|
||||
|
||||
用于编写 Vector3(0, -1, 0) 的简便方法。
|
||||
|
||||
- 返回值
|
||||
|
||||
| 数据类型 | 说明 |
|
||||
| :------- | :-------------------- |
|
||||
| Vector3 | 返回Vector3(0, -1, 0) |
|
||||
|
||||
- 示例
|
||||
|
||||
```python
|
||||
from common.utils.mcmath import Vector3
|
||||
newOne = Vector3.Down()
|
||||
```
|
||||
|
||||
|
||||
|
||||
### Left
|
||||
|
||||
- 描述
|
||||
|
||||
用于编写 Vector3(-1, 0, 0) 的简便方法，对应MC中的西面。
|
||||
|
||||
- 返回值
|
||||
|
||||
| 数据类型 | 说明 |
|
||||
| :------- | :-------------------- |
|
||||
| Vector3 | 返回Vector3(-1, 0, 0) |
|
||||
|
||||
- 示例
|
||||
|
||||
```python
|
||||
from common.utils.mcmath import Vector3
|
||||
newOne = Vector3.Left()
|
||||
```
|
||||
|
||||
|
||||
|
||||
### Right
|
||||
|
||||
- 描述
|
||||
|
||||
用于编写 Vector3(1, 0, 0) 的简便方法，对应MC中的东面。
|
||||
|
||||
- 返回值
|
||||
|
||||
| 数据类型 | 说明 |
|
||||
| :------- | :------------------- |
|
||||
| Vector3 | 返回Vector3(1, 0, 0) |
|
||||
|
||||
- 示例
|
||||
|
||||
```python
|
||||
from common.utils.mcmath import Vector3
|
||||
newOne = Vector3.Right()
|
||||
```
|
||||
|
||||
|
||||
|
||||
### Forward
|
||||
|
||||
- 描述
|
||||
|
||||
用于编写 Vector3(0, 0, 1) 的简便方法，对应MC中的南面。
|
||||
|
||||
- 返回值
|
||||
|
||||
| 数据类型 | 说明 |
|
||||
| :------- | :------------------- |
|
||||
| Vector3 | 返回Vector3(0, 0, 1) |
|
||||
|
||||
- 示例
|
||||
|
||||
```python
|
||||
from common.utils.mcmath import Vector3
|
||||
newOne = Vector3.Forward()
|
||||
```
|
||||
|
||||
|
||||
|
||||
### Backward
|
||||
|
||||
- 描述
|
||||
|
||||
用于编写 Vector3(0, 0, -1) 的简便方法，对应MC中的北面。
|
||||
|
||||
- 返回值
|
||||
|
||||
| 数据类型 | 说明 |
|
||||
| :------- | :-------------------- |
|
||||
| Vector3 | 返回Vector3(0, 0, -1) |
|
||||
|
||||
- 示例
|
||||
|
||||
```python
|
||||
from common.utils.mcmath import Vector3
|
||||
newOne = Vector3.Backward()
|
||||
```
|
||||
|
||||
|
||||
|
||||
### Dot
|
||||
|
||||
- 描述
|
||||
|
||||
两个向量的点积。
|
||||
|
||||
点积是一个浮点值，它等于 将两个向量的大小相乘，然后乘以向量之间角度的余弦值。
|
||||
|
||||
对于 normalized 向量，如果它们指向完全相同的方向，Dot 返回 1； 如果它们指向完全相反的方向，返回 -1；如果向量彼此垂直，则 Dot 返回 0。
|
||||
|
||||
- 参数
|
||||
|
||||
| 参数名 | 数据类型 | 说明 |
|
||||
| ------ | :------- | :---- |
|
||||
| a | Vector3 | 向量a |
|
||||
| b | Vector3 | 向量b |
|
||||
|
||||
- 返回值
|
||||
|
||||
| 数据类型 | 说明 |
|
||||
| :------- | :------------- |
|
||||
| float | 两个向量的点积 |
|
||||
|
||||
- 示例
|
||||
|
||||
```python
|
||||
from common.utils.mcmath import Vector3
|
||||
a = Vector3(1, 2, 3)
|
||||
b = Vector3(0, 3, 1)
|
||||
c = Vector3.Dot(a, b) # 1 * 0 + 2 * 3 + 3 * 1 = 9
|
||||
```
|
||||
|
||||
|
||||
|
||||
### Cross
|
||||
|
||||
- 描述
|
||||
|
||||
两个向量的叉积。
|
||||
|
||||
两个向量的叉积生成第三个向量， 该向量垂直于两个输入向量。结果的大小等于： 将两个输入的大小相乘，然后乘以输入之间角度的正弦值。 可以使用“右手定则”确定结果向量的方向。用右手的四指先表示向量a的方向，然后手指朝着手心的方向摆动到向量b的方向，大拇指所指的方向就是向量c的方向。
|
||||
|
||||
- 参数
|
||||
|
||||
| 参数名 | 数据类型 | 说明 |
|
||||
| ------ | :------- | :---- |
|
||||
| a | Vector3 | 向量a |
|
||||
| b | Vector3 | 向量b |
|
||||
|
||||
- 返回值
|
||||
|
||||
| 数据类型 | 说明 |
|
||||
| :------- | :------------- |
|
||||
| float | 两个向量的点积 |
|
||||
|
||||
- 示例
|
||||
|
||||
```python
|
||||
from common.utils.mcmath import Vector3
|
||||
a = Vector3(1, 2, 3)
|
||||
b = Vector3(0, 3, 1)
|
||||
c = Vector3.Cross(a, b)
|
||||
```
|
||||
|
||||
|
||||
|
||||
## 成员方法
|
||||
|
||||
### Length
|
||||
|
||||
- 描述
|
||||
|
||||
返回该向量的长度。
|
||||
|
||||
向量长度为 `(x*x+y*y+z*z)` 的平方根。
|
||||
|
||||
如果只需要比较一些向量的大小， 则可以使用LengthSquared()函数比较它们的平方数（计算平方数更快）。
|
||||
|
||||
- 返回值
|
||||
|
||||
| 数据类型 | 说明 |
|
||||
| :------- | :--------------- |
|
||||
| float | 该向量的长度 |
|
||||
|
||||
- 示例
|
||||
|
||||
```python
|
||||
from common.utils.mcmath import Vector3
|
||||
a = Vector3(3, 4, 0)
|
||||
print a.Length() # 打印 5.0
|
||||
```
|
||||
|
||||
|
||||
|
||||
### LengthSquared
|
||||
|
||||
- 描述
|
||||
|
||||
返回该向量的长度的平方。
|
||||
|
||||
- 返回值
|
||||
|
||||
| 数据类型 | 说明 |
|
||||
| :------- | :------------------- |
|
||||
| float | 该向量的长度的平方 |
|
||||
|
||||
- 示例
|
||||
|
||||
```python
|
||||
from common.utils.mcmath import Vector3
|
||||
a = Vector3(3, 4, 0)
|
||||
print a.LengthSquared() # 打印 25.0
|
||||
```
|
||||
|
||||
|
||||
|
||||
### ToTuple
|
||||
|
||||
- 描述
|
||||
|
||||
返回该向量的tuple形式(x, y, z)，便于玩家转换后作为其他事件的参数进行传递。
|
||||
|
||||
- 返回值
|
||||
|
||||
| 数据类型 | 说明 |
|
||||
| :------- | :----------------------------- |
|
||||
| tuple | 返回该向量的tuple形式(x, y, z) |
|
||||
|
||||
- 示例
|
||||
|
||||
```python
|
||||
from common.utils.mcmath import Vector3
|
||||
a = Vector3(3, 4, 0)
|
||||
print a.ToTuple() # 打印 (3, 4, 0)
|
||||
```
|
||||
|
||||
|
||||
|
||||
### Normalized
|
||||
|
||||
- 描述
|
||||
|
||||
返回长度为 1 时的该向量。
|
||||
|
||||
进行标准化时，向量方向保持不变，但其长度为 1.0。
|
||||
|
||||
请注意，当前向量保持不变，返回一个新的归一化向量。如果 要归一化当前向量，请使用Normalize函数。
|
||||
|
||||
如果向量太小而无法标准化，则返回零向量。
|
||||
|
||||
- 返回值
|
||||
|
||||
| 数据类型 | 说明 |
|
||||
| :------- | :------------------- |
|
||||
| Vector3 | 该向量标准化后的向量 |
|
||||
|
||||
- 示例
|
||||
|
||||
```python
|
||||
from common.utils.mcmath import Vector3
|
||||
a = Vector3(3, 4, 0)
|
||||
print a.Normalized() # 打印结果(0.6, 0.8, 0)
|
||||
print a # 打印结果(3, 4, 0)，a并没有发生变化
|
||||
```
|
||||
|
||||
|
||||
|
||||
### Normalize
|
||||
|
||||
- 描述
|
||||
|
||||
使该向量标准化，向量方向保持不变，但其长度变为 1.0。
|
||||
|
||||
请注意，该函数无返回值，仅改变当前向量，如果要返回当前向量的标准化值且不改变该向量，请使用Normalized函数。
|
||||
|
||||
如果向量太小而无法标准化，则设置为零向量。
|
||||
|
||||
- 示例
|
||||
|
||||
```python
|
||||
from common.utils.mcmath import Vector3
|
||||
a = Vector3(3, 4, 0)
|
||||
a.Normalize()
|
||||
print a # 打印结果(0.6, 0.8, 0)，a被标准化
|
||||
```
|
||||
|
||||
|
||||
|
||||
### Set
|
||||
|
||||
- 描述
|
||||
|
||||
设置该向量的值
|
||||
|
||||
- 参数
|
||||
|
||||
| 参数名 | 数据类型 | 说明 |
|
||||
| ------ | :------- | :---------- |
|
||||
| x | float | 向量的x分量 |
|
||||
| y | float | 向量的y分量 |
|
||||
| z | float | 向量的z分量 |
|
||||
|
||||
- 示例
|
||||
|
||||
```python
|
||||
from common.utils.mcmath import Vector3
|
||||
a = Vector3(3, 4, 0)
|
||||
a.Set(1, 2, 3)
|
||||
print a # 打印结果(1, 2, 3)
|
||||
```
|
||||
|
||||
|
||||
|
||||
## 成员变量
|
||||
|
||||
- 描述
|
||||
|
||||
可以直接通过`.`运算符访问向量的x、y、z分量。也可以通过`[]`直接获取，0、1、2分别对应x、y、z。但不能直接通过该方法对各个分量进行设置，只能通过Set方法来进行设置。
|
||||
|
||||
- 示例
|
||||
|
||||
```python
|
||||
from common.utils.mcmath import Vector3
|
||||
a = Vector3(3, 4, 5)
|
||||
print a.x # 3
|
||||
print a.y # 4
|
||||
print a.z # 5
|
||||
print a[0] # 3
|
||||
print a[1] # 4
|
||||
print a[2] # 5
|
||||
```
|
||||
|
||||
|
||||
|
||||
## 运算符
|
||||
|
||||
### operate +
|
||||
|
||||
- 描述
|
||||
|
||||
向量加法，两向量相加等于各分量之和。向量与常数相加等于各分量分别加上该常数。
|
||||
|
||||
- 示例
|
||||
|
||||
```python
|
||||
from common.utils.mcmath import Vector3
|
||||
a = Vector3(3, 4, 0)
|
||||
b = Vector3.One()
|
||||
print a + 5 # 打印结果(8, 9, 5)
|
||||
print a + b # 打印结果(4, 5, 1)
|
||||
```
|
||||
|
||||
|
||||
|
||||
### operate -
|
||||
|
||||
- 描述
|
||||
|
||||
向量减法，两向量相加等于各分量之差。向量与常数相减等于各分量分别与该常数求差。
|
||||
|
||||
向量求反，返回相反方向的向量
|
||||
|
||||
- 示例
|
||||
|
||||
```python
|
||||
from common.utils.mcmath import Vector3
|
||||
a = Vector3(3, 4, 0)
|
||||
b = Vector3.One()
|
||||
print a - 2 # 打印结果(1, 2, -2)
|
||||
print 2 - a # 打印结果(-1, -2, 2)
|
||||
print a - b # 打印结果(2, 3, -1)
|
||||
print -a # 打印结果(-3, -4, 0)
|
||||
```
|
||||
|
||||
|
||||
|
||||
### operate \*
|
||||
|
||||
- 描述
|
||||
|
||||
向量乘法，两向量相乘等于各分量相乘相加，即向量点积，等价于Vector3.Dot(a, b)。向量与常数相乘等于各分量分别乘以该常数。
|
||||
|
||||
- 示例
|
||||
|
||||
```python
|
||||
from common.utils.mcmath import Vector3
|
||||
a = Vector3(3, 4, 0)
|
||||
b = Vector3.Up()
|
||||
print a * 2 # 打印结果(6, 8, 0)
|
||||
print a * b # 打印结果4
|
||||
```
|
||||
|
||||
|
||||
|
||||
### operate /
|
||||
|
||||
- 描述
|
||||
|
||||
向量除法，仅支持向量与常数相除，等于各分量分别除以该常数。
|
||||
|
||||
- 示例
|
||||
|
||||
```python
|
||||
from common.utils.mcmath import Vector3
|
||||
a = Vector3(3, 4, 0)
|
||||
b = Vector3.One()
|
||||
print a / 2 # 打印结果(1.5, 2, 0)
|
||||
```
|
||||
|
||||
|
||||
|
||||
### operate ==
|
||||
|
||||
- 描述
|
||||
|
||||
判断两个向量是否相等，当各分量均相等时返回True
|
||||
|
||||
|
||||
|
||||
### operate !=
|
||||
|
||||
- 描述
|
||||
|
||||
判断两个向量是否不等，当各分量均相等时返回False
|
||||
413
mcguide/20-玩法开发/10-基本概念/11-Quaternion.md
Normal file
413
mcguide/20-玩法开发/10-基本概念/11-Quaternion.md
Normal file
@@ -0,0 +1,413 @@
|
||||
---
|
||||
front:
|
||||
hard: 入门
|
||||
time: 分钟
|
||||
---
|
||||
|
||||
# Quaternion
|
||||
|
||||
- 描述
|
||||
|
||||
四元数用于表示旋转。
|
||||
|
||||
它们结构紧凑，不受万向锁影响。
|
||||
|
||||
它们基于复数，不容易理解。 您几乎不会有机会访问或修改单个四元数分量（x、y、z、w）
|
||||
|
||||
您可以使用乘法对旋转进行旋转，或对向量进行旋转。
|
||||
|
||||
## 构造函数
|
||||
|
||||
### Quaternion(x, y, z, w)
|
||||
|
||||
- 描述
|
||||
|
||||
用于构造一个旋转。
|
||||
|
||||
- 参数
|
||||
|
||||
| 参数名 | 数据类型 | 说明 |
|
||||
| ------ | :------- | :------------------------------------ |
|
||||
| x | float | 四元数的x分量 |
|
||||
| y | float | 四元数的y分量 |
|
||||
| z | float | 四元数的z分量 |
|
||||
| w | float | 四元数的 w 分量。请勿直接修改四元数。 |
|
||||
|
||||
- 返回值
|
||||
|
||||
| 数据类型 | 说明 |
|
||||
| :--------- | :------------------------- |
|
||||
| Quaternion | 返回Quaternion(x, y, z, w) |
|
||||
|
||||
- 示例
|
||||
|
||||
```python
|
||||
from common.utils.mcmath import Quaternion
|
||||
q = Quaternion(1, 2, 3, 4)
|
||||
```
|
||||
|
||||
|
||||
|
||||
### Quaternion(vecTuple)
|
||||
|
||||
- 描述
|
||||
|
||||
用于构造一个旋转。
|
||||
|
||||
- 参数
|
||||
|
||||
| 参数名 | 数据类型 | 说明 |
|
||||
| -------- | :-------------------------------- | :----------------- |
|
||||
| vecTuple | tuple(float, float, float, float) | 长度为4的tuple数组 |
|
||||
|
||||
- 返回值
|
||||
|
||||
| 数据类型 | 说明 |
|
||||
| :--------- | :----------------------------------------------------------- |
|
||||
| Quaternion | 返回Quaternion(vecTuple[0], vecTuple[1], vecTuple[2], vecTuple[3]) |
|
||||
|
||||
- 示例
|
||||
|
||||
```python
|
||||
from common.utils.mcmath import Quaternion
|
||||
a = (0, 0, 0, 1)
|
||||
q = Quaternion(a)
|
||||
```
|
||||
|
||||
|
||||
|
||||
## 静态方法
|
||||
|
||||
可以直接通过Quaternion.MethodName()调用的静态方法，无需创建实例。
|
||||
|
||||
### AngleAxis
|
||||
|
||||
- 描述
|
||||
|
||||
创建一个围绕 `axis` 旋转 `angle` 度的旋转
|
||||
|
||||
- 参数
|
||||
|
||||
| 参数名 | 数据类型 | 说明 |
|
||||
| ------ | :------- | :------- |
|
||||
| angle | float | 旋转角度 |
|
||||
| axis | Vector3 | 旋转轴 |
|
||||
|
||||
- 返回值
|
||||
|
||||
| 数据类型 | 说明 |
|
||||
| :--------- | :-------------------------------- |
|
||||
| Quaternion | 围绕 `axis` 旋转 `angle` 度的旋转 |
|
||||
|
||||
- 示例
|
||||
|
||||
```python
|
||||
from common.utils.mcmath import Quaternion
|
||||
newQuaternion = Quaternion.AngleAxis(45, Vector3.Up()) # 创建一个围绕y轴旋转45°的旋转
|
||||
```
|
||||
|
||||
|
||||
|
||||
### Euler
|
||||
|
||||
- 描述
|
||||
|
||||
创建一个先围绕 Z 轴旋转 z 度、再围绕 X 轴旋转 x 度、最后围绕 Y 轴旋转 y 度的旋转（注意顺序）。注意：如果该欧拉旋转出现万向节锁，会导致四元数返回的EulerAngle异常
|
||||
|
||||
- 参数
|
||||
|
||||
| 参数名 | 数据类型 | 说明 |
|
||||
| ------ | :------- | :---------------- |
|
||||
| x | float | 围绕x轴旋转的角度 |
|
||||
| y | float | 围绕y轴旋转的角度 |
|
||||
| z | float | 围绕z轴旋转的角度 |
|
||||
|
||||
- 返回值
|
||||
|
||||
| 数据类型 | 说明 |
|
||||
| :--------- | :----------------------------------------------------------- |
|
||||
| Quaternion | 先围绕 Z 轴旋转 z 度、再围绕 X 轴旋转 x 度、最后围绕 Y 轴旋转 y 度的旋转 |
|
||||
|
||||
- 示例
|
||||
|
||||
```python
|
||||
from common.utils.mcmath import Quaternion
|
||||
newQuaternion = Quaternion.Euler(30, 15, 45) # 创建一个先围绕z轴旋转45°、再围绕x轴旋转30°、最后围绕y轴旋转45°的旋转
|
||||
```
|
||||
|
||||
|
||||
|
||||
### Dot
|
||||
|
||||
- 描述
|
||||
|
||||
两个旋转的点积。
|
||||
|
||||
点积是一个浮点值，它等于两个旋转对应分量之积求和。
|
||||
|
||||
- 参数
|
||||
|
||||
| 参数名 | 数据类型 | 说明 |
|
||||
| ------ | :--------- | :---- |
|
||||
| a | Quaternion | 旋转a |
|
||||
| b | Quaternion | 旋转b |
|
||||
|
||||
- 返回值
|
||||
|
||||
| 数据类型 | 说明 |
|
||||
| :------- | :------------- |
|
||||
| float | 两个向量的点积 |
|
||||
|
||||
- 示例
|
||||
|
||||
```python
|
||||
from common.utils.mcmath import Quaternion
|
||||
a = Quaternion(1, 2, 3, 1)
|
||||
b = Quaternion(0, 3, 1, 1)
|
||||
c = Quaternion.Dot(a, b) # 1 * 0 + 2 * 3 + 3 * 1 + 1 * 1 = 10
|
||||
```
|
||||
|
||||
|
||||
|
||||
### Cross
|
||||
|
||||
- 描述
|
||||
|
||||
两个旋转格拉瑟曼积，Cross(a, b)表示旋转a后再旋转p的合成旋转。也可以直接通过a * b得到。
|
||||
|
||||
- 参数
|
||||
|
||||
| 参数名 | 数据类型 | 说明 |
|
||||
| ------ | :--------- | :---- |
|
||||
| a | Quaternion | 旋转a |
|
||||
| b | Quaternion | 旋转b |
|
||||
|
||||
- 返回值
|
||||
|
||||
| 数据类型 | 说明 |
|
||||
| :--------- | :------------------- |
|
||||
| Quaternion | 两个向量的格拉斯曼积 |
|
||||
|
||||
- 示例
|
||||
|
||||
```python
|
||||
from common.utils.mcmath import Quaternion
|
||||
a = Quaternion(1, 2, 3, 1)
|
||||
b = Quaternion(0, 3, 1, 1)
|
||||
c = Quaternion.Cross(a, b)
|
||||
```
|
||||
|
||||
|
||||
|
||||
### Conjugate
|
||||
|
||||
- 描述
|
||||
|
||||
返回该旋转的共轭旋转，其w分量不变，其他分量分别取反
|
||||
|
||||
- 参数
|
||||
|
||||
| 参数名 | 数据类型 | 说明 |
|
||||
| ------ | :--------- | :---- |
|
||||
| q | Quaternion | 旋转q |
|
||||
|
||||
- 返回值
|
||||
|
||||
| 数据类型 | 说明 |
|
||||
| :--------- | :----------- |
|
||||
| Quaternion | 返回共轭旋转 |
|
||||
|
||||
- 示例
|
||||
|
||||
```python
|
||||
from common.utils.mcmath import Quaternion
|
||||
a = Quaternion(1, 2, 3, 1)
|
||||
b = Quaternion.Conjugate(a) # (-1, -2, -3, 1)
|
||||
```
|
||||
|
||||
|
||||
|
||||
### Inverse
|
||||
|
||||
- 描述
|
||||
|
||||
返回该旋转的逆旋转，如果旋转q的模长为1，那么q*q<sup>-1</sup>将会得到零旋转(0, 0, 0, 1)
|
||||
|
||||
- 参数
|
||||
|
||||
| 参数名 | 数据类型 | 说明 |
|
||||
| ------ | :--------- | :---- |
|
||||
| q | Quaternion | 旋转q |
|
||||
|
||||
- 返回值
|
||||
|
||||
| 数据类型 | 说明 |
|
||||
| :--------- | :---------------- |
|
||||
| Quaternion | 返回旋转q的逆旋转 |
|
||||
|
||||
- 示例
|
||||
|
||||
```python
|
||||
from common.utils.mcmath import Quaternion
|
||||
a = Quaternion(1, 2, 3, 1)
|
||||
a.Normalize() # 将a标准化
|
||||
b = Quaternion.Inverse(a) # b为a的逆旋转
|
||||
print a * b # 打印结果约为 (0, 0, 0, 1)， 可能因为精度问题出现极小的非零数
|
||||
```
|
||||
|
||||
|
||||
|
||||
## 成员方法
|
||||
|
||||
### Length
|
||||
|
||||
- 描述
|
||||
|
||||
返回该向量的长度。
|
||||
|
||||
向量长度为 `(x*x+y*y+z*z)` 的平方根。
|
||||
|
||||
如果只需要比较一些向量的大小， 则可以使用LengthSquared()函数比较它们的平方数（计算平方数更快）。
|
||||
|
||||
- 返回值
|
||||
|
||||
| 数据类型 | 说明 |
|
||||
| :------- | :--------------- |
|
||||
| float | 该向量的长度 |
|
||||
|
||||
- 示例
|
||||
|
||||
```python
|
||||
from common.utils.mcmath import Quaternion
|
||||
q = Quaternion(3, 4, 0, 0)
|
||||
print q.Length() # 打印 5
|
||||
```
|
||||
|
||||
|
||||
|
||||
### LengthSquared
|
||||
|
||||
- 描述
|
||||
|
||||
返回该向量的长度的平方。
|
||||
|
||||
- 返回值
|
||||
|
||||
| 数据类型 | 说明 |
|
||||
| :------- | :------------------- |
|
||||
| float | 该向量的长度的平方 |
|
||||
|
||||
- 示例
|
||||
|
||||
```python
|
||||
from common.utils.mcmath import Quaternion
|
||||
q = Quaternion(3, 4, 0, 0)
|
||||
print q.LengthSquared() # 打印 25
|
||||
```
|
||||
|
||||
|
||||
|
||||
### ToTuple
|
||||
|
||||
- 描述
|
||||
|
||||
返回该向量的tuple形式(x, y, z, w)，便于玩家转换后作为其他事件的参数进行传递。
|
||||
|
||||
- 返回值
|
||||
|
||||
| 数据类型 | 说明 |
|
||||
| :------- | :-------------------------------- |
|
||||
| tuple | 返回该向量的tuple形式(x, y, z, w) |
|
||||
|
||||
- 示例
|
||||
|
||||
```python
|
||||
from common.utils.mcmath import Quaternion
|
||||
q = Quaternion(0, 0, 0, 1)
|
||||
print q.ToTuple() # 打印 (0, 0, 0, 1)
|
||||
```
|
||||
|
||||
|
||||
|
||||
### Normalized
|
||||
|
||||
- 描述
|
||||
|
||||
返回该四元数，并且量值为 1。
|
||||
|
||||
进行归一化时，四元数方向保持不变，但其量值为 1.0。
|
||||
|
||||
请注意，当前四元数保持不变，返回一个新的归一化四元数。如果 要归一化原始四元数，请改用Normalize方法。
|
||||
|
||||
如果四元数太小而无法归一化，则会返回(0, 0, 0, 1)，表示零旋转。
|
||||
|
||||
- 返回值
|
||||
|
||||
| 数据类型 | 说明 |
|
||||
| :--------- | :--------------------- |
|
||||
| Quaternion | 该向量标准化后的四元数 |
|
||||
|
||||
- 示例
|
||||
|
||||
```python
|
||||
from common.utils.mcmath import Quaternion
|
||||
q = Quaternion(3, 4, 0, 0)
|
||||
print q.Normalized() # 打印结果(0.6, 0.8, 0, 0)
|
||||
print q # 打印结果(3, 4, 0, 0)，q并没有发生变化
|
||||
```
|
||||
|
||||
|
||||
|
||||
### Normalize
|
||||
|
||||
- 描述
|
||||
|
||||
使该向量标准化，向量方向保持不变，但其长度变为 1.0。
|
||||
|
||||
请注意，该函数无返回值，仅改变当前向量，如果要返回当前向量的标准化值且不改变该向量，请使用Normalized函数。
|
||||
|
||||
如果向量太小而无法标准化，则设置为零向量。
|
||||
|
||||
- 示例
|
||||
|
||||
```python
|
||||
from common.utils.mcmath import Quaternion
|
||||
q = Quaternion(3, 4, 0, 0)
|
||||
q.Normalize()
|
||||
print q # 打印结果(0.6, 0.8, 0, 0)，q被标准化
|
||||
```
|
||||
|
||||
|
||||
|
||||
### EulerAngles
|
||||
|
||||
- 描述
|
||||
|
||||
返回围绕 z 轴旋转 euler.z 度、围绕 x 轴旋转 euler.x 度、围绕 y 轴旋转 euler.y 度（按此顺序）的旋转。可以从四元数中读取欧拉角。注意：如果该欧拉旋转出现万向节锁，会导致四元数返回的EulerAngle异常
|
||||
|
||||
- 示例
|
||||
|
||||
```python
|
||||
from common.utils.mcmath import Quaternion
|
||||
q = Quaternion.Euler(30, 15, 45) # 创建一个先围绕z轴旋转45°、再围绕x轴旋转30°、最后围绕y轴旋转45°的旋转
|
||||
print q.EulerAngles() # 打印结果(30, 15, 45)
|
||||
```
|
||||
|
||||
|
||||
|
||||
## 运算符
|
||||
|
||||
### operate *
|
||||
|
||||
- 描述
|
||||
|
||||
旋转乘法，两个旋转相乘表示先旋转运算符左侧的旋转，再旋转运算符右侧的旋转。等价于Quaternion.Cross(a, b)。不满足乘法交换律，即`a*b != b*a`
|
||||
|
||||
|
||||
|
||||
### operate ==
|
||||
|
||||
- 描述
|
||||
|
||||
判断两个旋转是否相等，只有当各分量均相等时返回True
|
||||
|
||||
371
mcguide/20-玩法开发/10-基本概念/12-Matrix.md
Normal file
371
mcguide/20-玩法开发/10-基本概念/12-Matrix.md
Normal file
@@ -0,0 +1,371 @@
|
||||
---
|
||||
front:
|
||||
hard: 入门
|
||||
time: 分钟
|
||||
---
|
||||
|
||||
# Matrix
|
||||
|
||||
- 描述
|
||||
|
||||
矩阵（Matrix）是一个按照长方阵列排列的复数或实数集合，在计算机图形学中，常用作物体位置、运动等数学描述
|
||||
|
||||
## 构造函数
|
||||
|
||||
### Matrix(rowNum, colNum)
|
||||
|
||||
- 描述
|
||||
|
||||
用于构造一个rowNum行,colNum列的零矩阵。
|
||||
|
||||
- 参数
|
||||
|
||||
| 参数名 | 数据类型 | 说明 |
|
||||
| ------ | :------- | :------------------------------------ |
|
||||
| rowNum | int | 矩阵行数 |
|
||||
| colNum | int | 矩阵列数 |
|
||||
|
||||
- 返回值
|
||||
|
||||
| 数据类型 | 说明 |
|
||||
| :--------- | :------------------------- |
|
||||
| Matrix | 返回Matrix(rowNum, colNum)的零矩阵 |
|
||||
|
||||
- 示例
|
||||
|
||||
```python
|
||||
from common.utils.mcmath import Matrix
|
||||
q = Matrix(3, 4)
|
||||
```
|
||||
|
||||
## 静态方法
|
||||
|
||||
可以直接通过Matrix.MethodName()调用的静态方法，无需创建实例。
|
||||
|
||||
### CreateEye
|
||||
|
||||
- 描述
|
||||
|
||||
创建一个单位矩阵
|
||||
|
||||
- 参数
|
||||
|
||||
| 参数名 | 数据类型 | 说明 |
|
||||
| ------ | :------- | :------- |
|
||||
| rowNum/colNum | int | 矩阵行/列数 |
|
||||
|
||||
|
||||
- 返回值
|
||||
|
||||
| 数据类型 | 说明 |
|
||||
| :--------- | :-------------------------------- |
|
||||
| Matrix | 返回Matrix(num, num) 的单位矩阵|
|
||||
|
||||
- 示例
|
||||
|
||||
```python
|
||||
from common.utils.mcmath import Matrix
|
||||
newMatrix = Matrix.CreateEye(3)
|
||||
```
|
||||
|
||||
### Create
|
||||
|
||||
- 描述
|
||||
|
||||
通过数字列表创建一个矩阵
|
||||
|
||||
- 参数
|
||||
|
||||
| 参数名 | 数据类型 | 说明 |
|
||||
| ------ | :------- | :------- |
|
||||
| data | list(list(int/float)) | 矩阵数据源 |
|
||||
|
||||
|
||||
- 返回值
|
||||
|
||||
| 数据类型 | 说明 |
|
||||
| :--------- | :-------------------------------- |
|
||||
| Matrix | 返回Matrix(len(data), len(data[0])) ,数据为data的矩阵|
|
||||
|
||||
- 示例
|
||||
|
||||
```python
|
||||
from common.utils.mcmath import Matrix
|
||||
data = [[1,2,3], [4,5,6], [7,8,9]]
|
||||
newMatrix = Matrix.Create(data)
|
||||
```
|
||||
|
||||
### FromEulerXYZ
|
||||
|
||||
- 描述
|
||||
|
||||
创建欧拉角对应的旋转矩阵，以xyz的旋转顺序应用
|
||||
|
||||
- 参数
|
||||
|
||||
| 参数名 | 数据类型 | 说明 |
|
||||
| ------ | :------- | :------- |
|
||||
| Euler | tuple(xAngle, yAngle, zAngle) | 欧拉角 |
|
||||
|
||||
|
||||
- 返回值
|
||||
|
||||
| 数据类型 | 说明 |
|
||||
| :--------- | :-------------------------------- |
|
||||
| Matrix | 返回欧拉角对应的Matrix|
|
||||
|
||||
- 示例
|
||||
|
||||
```python
|
||||
from common.utils.mcmath import Matrix
|
||||
data = (30, 65, 20)
|
||||
newMatrix = Matrix.FromEulerXYZ(data)
|
||||
```
|
||||
|
||||
### ToEulerXYZ
|
||||
|
||||
- 描述
|
||||
|
||||
返回矩阵对应的欧拉角
|
||||
|
||||
- 参数
|
||||
|
||||
| 参数名 | 数据类型 | 说明 |
|
||||
| ------ | :------- | :------- |
|
||||
| mat | Matrix | 旋转矩阵 |
|
||||
|
||||
|
||||
- 返回值
|
||||
|
||||
| 数据类型 | 说明 |
|
||||
| :--------- | :-------------------------------- |
|
||||
| Euler | tuple(xAngle, yAngle, zAngle)|
|
||||
|
||||
- 示例
|
||||
|
||||
```python
|
||||
from common.utils.mcmath import Matrix
|
||||
data = [30, 65, 20]
|
||||
newMatrix = Matrix.FromEulerXYZ(data)
|
||||
newEular = Matrix.ToEulerXYZ(newMatrix)
|
||||
```
|
||||
|
||||
### matrix4_multiply
|
||||
|
||||
- 描述
|
||||
|
||||
返回两个4*4矩阵相乘后结果
|
||||
|
||||
- 参数
|
||||
|
||||
| 参数名 | 数据类型 | 说明 |
|
||||
| ------ | :------- | :------- |
|
||||
| mat1 | Matrix | 左边矩阵,大小为4*4 |
|
||||
| mat2 | Matrix | 右边矩阵,大小为4*4 |
|
||||
|
||||
|
||||
- 返回值
|
||||
|
||||
| 数据类型 | 说明 |
|
||||
| :--------- | :-------------------------------- |
|
||||
| Matrix | 结果,大小为4*4 |
|
||||
|
||||
- 示例
|
||||
|
||||
```python
|
||||
from common.utils.mcmath import Matrix
|
||||
q = Matrix.Create([[1,2,3,4], [3,4,5,6], [5,6,7,8], [7,8,9,10]])
|
||||
p = Matrix.Create([[5,6,7,8], [7,8,9,10], [9,10,11,12], [11,12,13,14]])
|
||||
newMatrix = Matrix.matrix4_multiply(q, p) # 与q*p效果相同，但是只能用于4*4矩阵，并且实现更底层，因此运算速度更快
|
||||
```
|
||||
|
||||
## 成员方法
|
||||
|
||||
### Copy
|
||||
|
||||
- 描述
|
||||
|
||||
返回矩阵的拷贝
|
||||
|
||||
- 返回值
|
||||
|
||||
| 数据类型 | 说明 |
|
||||
| :--------- | :-------------------------------- |
|
||||
| Matrix | 结果 |
|
||||
|
||||
- 示例
|
||||
|
||||
```python
|
||||
from common.utils.mcmath import Matrix
|
||||
q = Matrix.Create([[1,2], [3,4]])
|
||||
print q.Copy()
|
||||
```
|
||||
|
||||
### Eye
|
||||
|
||||
- 描述
|
||||
|
||||
把矩阵设置成单位矩阵，要求该矩阵行列数相同，否则报错
|
||||
|
||||
- 示例
|
||||
|
||||
```python
|
||||
from common.utils.mcmath import Matrix
|
||||
q = Matrix.Create([[1,2], [3,4]])
|
||||
q.Eye()
|
||||
print q
|
||||
```
|
||||
|
||||
### SetData
|
||||
|
||||
- 描述
|
||||
|
||||
根据数据源设置矩阵数据，要求数据源行列大于等于矩阵，否则报错
|
||||
|
||||
- 参数
|
||||
|
||||
| 参数名 | 数据类型 | 说明 |
|
||||
| ------ | :------- | :------- |
|
||||
| data | list(list(int/float)) | 数据源 |
|
||||
|
||||
- 示例
|
||||
|
||||
```python
|
||||
from common.utils.mcmath import Matrix
|
||||
q = Matrix.Create([[1,2], [3,4]])
|
||||
q.SetData([[4,5], [6,7]])
|
||||
print q
|
||||
```
|
||||
|
||||
### Transpose
|
||||
|
||||
- 描述
|
||||
|
||||
返回转置矩阵
|
||||
|
||||
- 返回值
|
||||
|
||||
| 数据类型 | 说明 |
|
||||
| :------- | :-------------------------------- |
|
||||
| Matrix | 返回对应的转置矩阵 |
|
||||
|
||||
- 示例
|
||||
|
||||
```python
|
||||
from common.utils.mcmath import Matrix
|
||||
q = Matrix.Create([[1,2], [3,4]])
|
||||
print q.Transpose()
|
||||
```
|
||||
|
||||
### Inverse
|
||||
|
||||
- 描述
|
||||
|
||||
返回逆矩阵，矩阵必须是个方阵，否则函数报错
|
||||
|
||||
- 返回值
|
||||
|
||||
| 数据类型 | 说明 |
|
||||
| :--------- | :--------------------- |
|
||||
| Matrix | 返回对应的逆矩阵 |
|
||||
|
||||
- 示例
|
||||
|
||||
```python
|
||||
from common.utils.mcmath import Matrix
|
||||
q = Matrix.Create([[1,2], [3,4]])
|
||||
print q.Inverse()
|
||||
```
|
||||
|
||||
|
||||
### Decompose
|
||||
|
||||
- 描述
|
||||
|
||||
对矩阵进行位姿分解，分解成位移向量 * 旋转四元数 * 缩放向量。请注意，并非所有矩阵都可以位姿分解，若矩阵存在非线性变换，强行进行位姿分解会导致信息丢失
|
||||
|
||||
- 返回值
|
||||
|
||||
| 数据类型 | 说明 |
|
||||
| :--------- | :--------------------- |
|
||||
| tuple(float, float, float), tuple(float, float, float, float),tuple(float, float, float) | 返回矩阵对应的位移向量 * 旋转四元数 * 缩放向量 |
|
||||
|
||||
- 示例
|
||||
|
||||
```python
|
||||
from common.utils.mcmath import Matrix
|
||||
q = Matrix.Create([[2,0,0,1], [0,3,0,1], [1,1,1,1], [1,1,1,1]])
|
||||
print q.Decompose()
|
||||
```
|
||||
|
||||
### ToQuaternion
|
||||
|
||||
- 描述
|
||||
|
||||
返回矩阵的旋转四元数
|
||||
|
||||
- 返回值
|
||||
|
||||
| 数据类型 | 说明 |
|
||||
| :--------- | :--------------------- |
|
||||
| tuple(float, float, float, float)| 返回矩阵对应的旋转四元数 |
|
||||
|
||||
- 示例
|
||||
|
||||
```python
|
||||
from common.utils.mcmath import Matrix
|
||||
q = Matrix.Create([[2,0,0,1], [0,3,0,1], [1,1,1,1], [1,1,1,1]])
|
||||
print q.ToQuaternion()
|
||||
```
|
||||
|
||||
|
||||
## 运算符
|
||||
|
||||
### operate +
|
||||
|
||||
- 描述
|
||||
|
||||
矩阵加法，两个矩阵相加表示向量的平移、多项式运算等，满足交换律、结合律，且要求两个矩阵行列数量相同
|
||||
|
||||
### operate *
|
||||
|
||||
- 描述
|
||||
|
||||
矩阵乘法，两个矩阵相乘表示线性映射、变换、多项式运算等，不满足交换律，但是满足结合律，且要求两个矩阵行列数量对应
|
||||
|
||||
### operate -
|
||||
|
||||
- 描述
|
||||
|
||||
矩阵减法，两个矩阵相加表示向量的平移、多项式运算等，满足交换律、结合律，且要求两个矩阵行列数量相同
|
||||
|
||||
|
||||
### operate `__str__`
|
||||
|
||||
- 描述
|
||||
|
||||
用于输出矩阵的字符串形式，即`print(matrix)`
|
||||
|
||||
### operate row
|
||||
|
||||
- 描述
|
||||
|
||||
返回矩阵的行数
|
||||
|
||||
### operate col
|
||||
|
||||
- 描述
|
||||
|
||||
返回矩阵的列数
|
||||
|
||||
### operate [int, int]
|
||||
|
||||
- 描述
|
||||
|
||||
返回矩阵的x行，y列的值,即`print mat[x,y]`
|
||||
|
||||
### operate [int, int]=
|
||||
|
||||
- 描述
|
||||
|
||||
设置矩阵x行y列的值，即`mat[x,y] = 1`
|
||||
BIN
mcguide/20-玩法开发/10-基本概念/picture/RightHand.jpg
Normal file
BIN
mcguide/20-玩法开发/10-基本概念/picture/RightHand.jpg
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 12 KiB |
BIN
mcguide/20-玩法开发/10-基本概念/picture/customtips_example.png
Normal file
BIN
mcguide/20-玩法开发/10-基本概念/picture/customtips_example.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 5.1 KiB |
Reference in New Issue
Block a user