#### 3.2.4 变量的访问权限
在C++中，变量的访问类型由类成员的属性决定，Public类型的表示其他类都可以访问，Protetced类型的成员表示子类可以访问，Private类型变量表示只有类内部函数可以访问此变量。
蓝图并没有类似的权限访问设计。
可以视可编辑(`Editable`)类型的变量作为Public类型变量，视不可编辑的变量作为Protected类型变量。
##### 3.2.4.1 私有变量
尽量不要把变量声明为private类型，除非一开始就打算这个变量永远只能被类内部访问，并且类本身也没打算被继承。尽量用`protected`，只有当你有非常清楚的理由要去限制子类的能力时，再使用private类型。
#### 3.2.5 高级显示
如果一个变量可以被编辑，但通常不会有人碰到，那么就把它标记为高级显示`Advanced Display`。这些变量在蓝图中会缺省隐藏，除非点击节点上的高级显示箭头。
有意思的是，`Advanced Display`这个选项本身，在编辑器的变量属性中也是一个高级显示类型的。
#### 3.2.6 Transient变量
Transient类型的变量是指那些不需要被序列化（保存或者加载），并且初始值为0或者null的变量。一般在引用其他对象时会使用，它们的值只有在运行时才确定。这样做能防止编辑器在磁盘上多存储一份多余的数据，以加快蓝图的存盘和加载速度。
因此，所有Transient类型变量都应该被初始化成0或者null。如果是其他值会增加调试bug的难度。
#### 3.2.8 Config变量
不要使用`Config Variable`标记，这会让设计师在控制蓝图行为上更加困难。这个标记一般用在C++中，用来标记那些极少被改变的变量，你可以认为它们是那些被标上`Advanced Advanced Display`的变量
### 3.3 函数、事件以及事件派发器
这一节用来解释应该如何管理函数、事件以及事件派发器。除非特殊说明，所有适用于函数的规则，同样适用于事件。
#### 3.3.1 函数命名
对于函数、事件以及事件派发器的命名极其重要，仅仅从一个名字本身，就有很多条件要考虑，比如说：
* 是纯虚函数吗？
* 是状态查询函数吗?
* 是事件响应函数吗?
* 是远程调用函数吗?
* 函数的目的是什么？
如果命名得当，这些问题甚至更多问题的答案会在名字中体现出来。
#### 3.3.1.1 所有函数的命名都应该是动词
所有函数和事件执行者都是需要做一些动作，可能是去获取信息，也可能是数据计算，或者搞点什么事情。因此，所有函数都应该用动词开始，并且用一般现代时态，并且有上下文来表明它们究竟在做什么
`OnRep` 这样的响应函数，事件具柄和事件派发器的命名不遵守这个规则。
好的例子:
* `Fire` - 如果类是一个角色或者武器，那么这是一个好命名，如果是木桶，玻璃，那这个函数就会让人困惑了。
* `Jump` - 如果类是一个角色，那么这是个好名字，如果不是，那么需要一些上下文来解释这个函数的含义
* `Explode`
* `ReceiveMessage`
* `SortPlayerArray`
* `GetArmOffset`
* `GetCoordinates`
* `UpdateTransforms`
* `EnableBigHeadMode`
* `IsEnemy` - ["Is" 是个动词](http://writingexplained.org/is-is-a-verb)
不好的例子:
* `Dead` - 是已经死了？还是死的动作?
* `Rock`
* `ProcessData` - 无意义，这个名字等于没说.
* `PlayerState` - 不能用名词
* `Color` - 如果是动词，那么缺少上下文，如果是名词，也不行.
#### 3.3.1.2 属性的状态变化响应函数应该命名为`OnRep_Variable`
所有用来响应状态变化的函数应该用`OnRep_Variable`的形式，这是由蓝图编辑器强制规定的，如果你在C++中写`OnRep`函数，应该同样遵守这个规则。
#### 3.3.1.3 返回布尔变量的信息查询函数应该是问询函数
如果一个函数不改变类的状态，并且只是返回信息、状态或者计算返回给调用者yes/no，这应该是一个问询函数。同样遵守[动词规则](#bp-funcs-naming-verbs)。
非常重要的是，应该假定这样的函数其实就是执行某种动作，并且返回动作是否执行成功。
好的例子:
* `IsDead`
* `IsOnFire`
* `IsAlive`
* `IsSpeaking`
* `IsHavingAnExistentialCrisis`
* `IsVisible`
* `HasWeapon` - ["Has" 是动词.](http://grammar.yourdictionary.com/parts-of-speech/verbs/Helping-Verbs.html)
* `WasCharging` - ["Was" 是动词"be"的过去式](http://grammar.yourdictionary.com/parts-of-speech/verbs/Helping-Verbs.html) 用 "was"表示查询以前的状态
* `CanReload` - ["Can"是动词](http://grammar.yourdictionary.com/parts-of-speech/verbs/Helping-Verbs.html)
坏的例子:
* `Fire` - 是查询正在开火？还是查询能不能开火？
* `OnFire` - 有可能和事件派发器函数混淆
* `Dead` - 是查询已经死亡？还是查询会不会死亡？
* `Visibility` - 是查询可见状态？还是设置可见状态？
#### 3.3.1.4 事件的响应函数和派发函数都应该以`On`开头
事件的响应函数和派发函数都应该以`On`开头，然后遵守[动词规则](#bp-funcs-naming-verbs)，如果是过去式，那么动词应该移到最后以方便阅读
在遵守动词规则的时候，需要优先考虑英语中的[固定句式](http://dictionary.cambridge.org/us/grammar/british-grammar/about-words-clauses-and-sentences/collocation)
有一些系统用`Handle`来表示事件响应，但在'Unreal'用的是`On`而不是`Handle`，
好的例子:
* `OnDeath` - Common collocation in games
* `OnPickup`
* `OnReceiveMessage`
* `OnMessageRecieved`
* `OnTargetChanged`
* `OnClick`
* `OnLeave`
坏的例子:
* `OnData`
* `OnTarget`
* `HandleMessage`
* `HandleDeath`
#### 3.3.1.5 远程调用函数应该用目标作为前缀
Any time an RPC is created, it should be prefixed with either `Server`, `Client`, or `Multicast`. No exceptions.
After the prefix, follow all other rules regarding function naming.
Good examples:
任何时候创建RPC函数，都应该把目标作为前缀放在前面，例如`Server`、 `Client`或者 `Multicast`，没有例外。
前缀之后的部分，遵守上面的其他规则。
好的例子:
* `ServerFireWeapon`
* `ClientNotifyDeath`
* `MulticastSpawnTracerEffect`
坏的例子:
* `FireWeapon` - 没有使用目标前缀
* `ServerClientBroadcast` - 混乱
* `AllNotifyDeath` - 用 `Multicast`, 不要用 `All`.
* `ClientWeapon` - 没有用动词, 让人困惑.
#### 3.3.2 所有函数都应该有返回节点
所有函数都应该有返回节点，没有例外。
返回节点明确标注了蓝图到此执行完毕。蓝图中的结构有可能有并行结构`Sequence`、循环结构`ForLoopWithBreak`或者逆向的回流节点组成，明确结束节点使蓝图易于阅读维护和调试。
如果启用了返回节点，当你的蓝图中有分支没有正常返回，或者流程有问题，蓝图的编译器会提出警告。
比如说，有程序员在并行序列中添加了一个新的分支，或者在循环体外添加逻辑但没有考虑到循环中的意外返回，那么这些情况都会造成蓝图的执行序列出现意外。蓝图编译器会立即给这些情况提出警告。
#### 3.3.3 蓝图函数中节点数不应该超过50个
简单来说，蓝图函数中的节点数应该小于50个，如果函数过于复杂，应该把它分割成几个小一点的函数，以便更好的阅读和维护。
在蓝图中添加以下节点不用计算个数，因为它们并不会增加蓝图的复杂度：
* Comment - 注释
* Route - 路由节点
* Cast - 类型转换节点
* Getting a Variable - 获取变量
* Breaking a Struct - 结构分解节点
* Function Entry - 函数入口
* Self - 自身节点
#### 3.3.4 所有Public函数都应该有功能描述
此规则更适用于公开或在市场出售的蓝图，以便其他人可以更轻松地浏览和使用您的蓝图。
简而言之，任何具有 Public 访问权限的函数都应该填写其描述。
#### 3.3.5 插件中可以在蓝图中调用的自定义函数都应该放在以插件名命名的类别中
如果你的工程包含插件，插件中定义了一些静态的可以被蓝图调用的函数，那么这些函数(`Category`)的类别应该被设置成插件的名称。
例如，`Zed Camera Interface` 或者 `Zed Camera Interface | Image Capturing`.
### 3.4 蓝图图形
本节包含了关于蓝图图形的内容
#### 3.4.1 不要画‘意面’
蓝图中所有连线都应该有清晰的开始点和结束点。你的蓝图不应该让阅读者在一堆乱糟糟的线中翻来翻去。以下内容可以帮你避免‘意大利面’样式的蓝图产生。
#### 3.4.2 保持连线对齐，而不是节点
不要试图让节点对齐，对齐的应该是连线。你无法控制一个节点的大小和上面连接点的位置，但你能通过控制节点的位置来控制连线。笔直的连线让整个蓝图清晰美观，歪歪扭扭的连线会让蓝图丑陋不堪。可以通过蓝图编辑器提供的功能直接让连线变直，方法是选择好节点，用快捷键Q
好的例子: 所有上面的节点的执行线都保持为直线。
不好的例子: 右上角节点的执行线歪了
可接受的例子: 有些节点无论你怎么用对齐工具都无法对齐，这种情况下，就尽量缩短它们之间连线的长度。
#### 3.4.3 白色的可执行线优先级最高
如果发现白色执行线和其他数据线无法同时对齐，白色执行线的优先级更高。
#### 3.4.4 蓝图需要有合理的注释
要善用蓝图的注释块，把相关的节点包含在注释块中，并在注释中描述这些功能节点的行为。虽然每个函数都应该被正确命名，以便每个单独的节点都易于理解，但仍然需要在注释中描述出为某个整体功能做出贡献的节点组的具体作用。如果一个函数没有很多节点块，并且很明显这些节点在函数目标中服务于最终目的，则不需要再对它们进行注释，函数名称和其描述中包含的信息就足够了。
#### 3.4.5 蓝图中需要在适当的地方处理类型转换错误
如果在函数或者蓝图事件处理过程中，总是假定类型转换应该是成功的，那么一旦出现类型转换失败，那应该及时报错，这使得其他模块得到通知，一件“应该正确工作”的函数没有正确工作。函数还应该在类型转换失败后，正确的恢复工作。
但这并不是强制要求所有的类型转换节点都要处理失败的情况，在很多情景中，尤其是类似于处理物理碰撞这样的事件中，处理类型转换失败就是悄悄结束而已就够了。
#### 3.4.6 避免出现空悬节点和死节点
所有蓝图中的节点都应该有其存在的意义，不要把空悬的节点，不会被执行的节点放在蓝图中
**[⬆ 返回顶层](#table-of-contents)**
## 4. 静态模型
这一节关注的是静态模型以及相关资源
### 4.1 静态模型的UV
使用Linter工具扫描工程报告错误和UV相关的错误时，如果您似乎无法追踪它，请打开项目的“Saved/Logs”文件夹中生成的“.log”文件，以获取有关失败原因的确切详细信息。 我希望将来能够将这些消息包含在Linter报告中。
#### 4.1.1 静态模型需要包含UV
很简单，所有的静态模型资源，不管他们要被怎么使用，都不应该不包含UV数据。
#### 4.1.2 静态模型的UV须要避免互相覆盖
同样很简单，所有的静态模型资源，不管他们要被怎么使用，都应该有正确的不互相覆盖的UV数据。
### 4.2 正确的设置LOD
这是一项工程级别的偏主观的检查，作为一条广为人知的规则，所有在玩家视野中会出现的物体，都应该正确的设置LOD数据。
### 4.3 不带插槽的模块化的模型需要严格对齐网格
这是一项针对每个具体资产的偏主观检查，模块化模型如何能够正确的对齐是基于工程设置中的和网格相关的设置。
模块对齐大小是2的幂还是10的倍数也是取决于项目设置，不过如果你想把你的资产在商城中出售，Epic的规定是对齐网格大小是10个单位或者更大。
### 4.4 所有模型需要有碰撞体
无论模型是否将会在关卡中产生物理碰撞，都应定义正确物理碰撞体数据。 这有助于引擎进行绑定盒计算、遮挡和照明等工作。 资产的碰撞体也需要良好的定义。
### 4.5 所有模型资源需要正确的缩放系数
这是一项工程级别的偏主观的检查，所有模型都应根据其项目设置正确的大小。 关卡设计师或蓝图作者大部分情况下都不必在使用模型时，再去调整模型的放缩系数。 在引擎中的缩放模型应被视为一种调整，而不是校正。
**[⬆ 返回顶层](#table-of-contents)**
## 5. Niagara
这一小节关注的是Niagara和相关资产。
### 5.1 永远都不要用空格
正如[禁止使用的字符](#00.1) 中提到的，标识符中严禁使用空格和所有空白字符。 对于 Niagara系统尤其如此，因为在Niagara中使用HLSL或其他脚本，当这些脚本尝试引用带空格的标识符时，会使事情变得更加困难。
(该条款贡献者为[@dunenkoff](https://github.com/Allar/ue5-style-guide/issues/58))
**[⬆ 返回顶层](#table-of-contents)**
## 6. 关卡 / 地图
[请参照术语中](#terms-level-map) 对 "关卡" 和 "地图"的解释
本小节关注的是关卡及其相关资产
### 6.1 解决掉错误和警告
所有关卡的加载对错误和警告都应为零容忍的。如果关卡加载时出现任何错误或警告，应立即修复它们以防止连锁问题。
您可以在控制台使用命令“map check”在编辑器中运行地图检查工具。
请注意：Linter对关卡的检查比编辑器更加严格，并且会捕获那些编辑器自行解决的错误。
### 6.2 记得构建光照
在项目开发过程中，偶尔没有构建照明是正常的。 然而在进行测试/内测/正式版构建时，或任何可能会分发的构建时，都应始终构建光照。
### 6.3 不要让玩家看到Z Fighting
不要让玩家在关卡中任何可见区域中发现[z-fighting](https://en.wikipedia.org/wiki/Z-fighting)。
### 6.4 商城需要遵守的规范
如果是需要上架UE商城的资源工程，需要额外遵守以下规范。
#### 6.4.1 预览场景
如果您的项目有可视的美术资产，则您的项目中必须有一个名称中带有“Overview”的地图。
而这张预览地图，应该遵守[Epic的规范](http://help.epicgames.com/customer/en/portal/articles/2592186-marketplace-submission-guidelines-preparing-your-assets#Required%20Levels%20and%20Maps).
例如, `InteractionComponent_Overview`.
#### 6.4.2 演示场景
如果您的项目中包含用于演示或者教学的资产，那么工程中有还需要一个名称中带有“Demo”的地图。 此地图应带有某种形式的文档，说明如何使用您的项目。 请参阅 Epic 提供的的"Content Examples project"，了解如何执行此操作的好范例。
如果您的项目主要是关于GamePlay或其他内容的，而不是美术资产，那么演示场景可以与预览场景是同一个场景。
例如, `InteractionComponent_Overview_Demo`, `ExplosionKit_Demo`.
**[⬆ 返回顶层](#table-of-contents)**
## 7. 纹理
本小节关注的是纹理及其相关资产
### 7.1 纹理尺寸必须是2的幂
所有纹理，尤其是UI纹理，纹理的尺寸必须是2的幂，但并不一定是正方形的。
例如, `128x512`, `1024x1024`, `2048x1024`, `1024x2048`, `1x512`.
### 7.2 纹理图案密度应该保持一致
所有纹理的大小都应适合项目的标准用例。 每个项目中定义的纹理密度各不相同，但同一个项目中的纹理应具有一致的密度。
例如，如果项目的纹理密度为每1单位8像素，那么用于渲染100x100单位的立方体所使用的纹理应为1024x1024，因为这是与项目纹理密度最接近且是2的幂的纹理尺寸了。
### 7.3 纹理大小不要超过8192
不应该使用超过8K的纹理，除非你有强烈的理由使用它。通常用大纹理只是再浪费资源
### 7.4 正确对纹理进行分组
每个纹理都应该属于一个正确的纹理组，用于做LOD计算，应根据纹理的用途正确设置。 例如，所有UI纹理都应属于UI纹理组
**[⬆ 返回顶层](#table-of-contents)**
## 主要贡献者
* [Michael Allar](http://allarsblog.com): [GitHub](https://github.com/Allar), [Twitter](https://twitter.com/michaelallar)
* [CosmoMyzrailGorynych](https://github.com/CosmoMyzrailGorynych)
* [billymcguffin](https://github.com/billymcguffin)
* [akenatsu](https://github.com/akenatsu)
## 版权声明
Copyright (c) 2016 Gamemakin LLC
See [LICENSE](/LICENSE)
**[⬆ 返回顶层](#table-of-contents)**
## 修正
我们鼓励您fork本规范并更根据团队的实际情况对本规范进行修改。但是建议您把所作的修改列在后面，这使您可以定期更新该规范，而不必处理合并冲突。
# };
================================================
FILE: README_PTBR.md
================================================
# [Gamemakin](https://gamemak.in) UE4 - Guia de Estilo() {
*Uma abordagem bastante razoável para Unreal Engine 4*
Inspirado pelo [Guia de Estilo Airbnb Javascript](https://github.com/airbnb/javascript).
[](#)
## Nota de tradução
Foram mantidos os nomes e expressões em inglês comumente usadas na Unreal Engine e.x. "texture", "material", "asset", etc.
## Aviso de Repo
O repo original agora está localizado em https://github.com/Allar/ue5-style-guide. O branch padrão deste repositório foi renomeado `main`.
## Atualmente, é para UE4.
## Documentação do Guia de Estilo e Linter
Mais documentação técnicas sobre o Linter e o Guia de Estilo pode ser encontrada na página: [LeiaOsDocumentos](https://ue4-style-guide.readthedocs.io/en/latest/).
## Debata este guia de estilo
Gamemakin LLC tem um canal Discord público em http://discord.gamemak.in com um canal #linter se você gostaria de debater sobre o Guia de Estilo e o plugin Linter.
## Link para este documento
Cada seção deste Guia de Estilo é numerada para facilitar a referência e o link. Você pode vincular a qualquer seção diretamente acrescentando uma hashtag e o número da seção ao final de http://ue4.style
Por exemplo, se você deseja enviar a alguém o primeiro princípio deste Guia de Estilo, você deve colocar `#0.1`, resultando em http://ue4.style#0.1.
## Forks e Traduções
Se você fez um fork ou tradução que não é adequada para uma solicitação pull neste repo, envie uma solicitação pull para adicionar sua fork ou tradução aqui.
* [Tradução para Coreano](https://github.com/ymkim50/ue4-style-guide/blob/master/README_Kor.md) por ymkim50
* [Tradução para Russo](https://github.com/CosmoMyzrailGorynych/ue4-style-guide-rus/blob/master/README.md) por CosmoMyzrailGorynych
* [Tradução para Japonês](https://github.com/akenatsu/ue4-style-guide/blob/master/README.jp.md) por akenatsu
* [Tradução para Chinês](https://github.com/skylens-inc/ue4-style-guide/blob/master/README.md) por Beijing Skylens Tech.
* [Tradução para Português do Brasil](https://github.com/danlvr/ue5-style-guide/blob/main/README_PTBR.md) por danlvr.
## Terminologia Importante
##### Levels/Maps
A palavra 'map' geralmente se refere ao que a pessoa chama de 'level' e pode ser usado indistintamente. Veja a história deste termo [aqui](https://en.wikipedia.org/wiki/Level_(video_gaming)).
##### Identifiers
Um `Identifier` é qualquer coisa que se pareça ou sirva como um "nome". Por exemplo, o nome de um "asset", ou o nome de um "material", ou a propriedade de um "blueprint", uma variável, ou um nome de pasta, ou para um nome de uma linha de tabela de dados, etc...
##### Caixa Alta e Caixa Baixa
Existem algumas maneiras diferentes de você `NomearComCaixaAltaOuCaixaBaixa`. Aqui estão alguns tipos mais comuns:
> ###### PascalCase
>
> Capitalize cada palavra e remova todos os espaços, e.x. `DesertEagle`, `GuiaDeEstilos`, `UmaSerieDePalavras`.
>
> ###### camelCase
>
> A primeira letra é sempre minúscula mas todas as palavras seguintes começam com maiúsculas, e.x. `desertEagle`, `guiaDeEstilos`, `umaSerieDePalavras`.
>
> ###### Snake_case
>
> As palavras podem começar arbitrariamente com letras maiúsculas ou minúsculas, mas as palavras são separadas por um sublinhado, e.g. `desert_Eagle`, `Guia_de_Estilos`, `uma_Serie_de_Palavras`.
##### Variáveis / Propriedades
As palavras 'variável' e 'propriedade' na maioria dos contextos são intercambiáveis. No entanto, se ambas forem usados juntos no mesmo contexto considere:
###### Propriedade
Normalmente se refere a uma variável definida em uma classe. Por exemplo, se `BP_Barril` tinha uma variável `bExplodiu`, `bExplodiu` pode ser referido como uma propriedade de `BP_Barril`.
Quando no contexto de uma classe, muitas vezes é usado para implicar o acesso a dados previamente definidos.
###### Variável
Normalmente se refere a uma variável definida como um argumento de função ou uma variável local dentro de uma função.
Quando no contexto de uma classe, é freqüentemente usado para transmitir um debate sobre sua definição e o que ela conterá.
## 0. Princípios
Esses princípios foram adaptados de [guida de estilo idomatic.js](https://github.com/rwaldron/idiomatic.js/).
### 0.1 Se o seu projeto UE4 já tem um Guia de Estilo, você deve segui-lo.
Se você estiver trabalhando em um projeto ou com uma equipe que possui um guia de estilo pré-existente, ele deve ser respeitado. Qualquer inconsistência entre um guia de estilo existente e este guia, deve-se seguir o existente.
Os guias de estilo devem ser documentos vivos. Você deve propor alterações de guia de estilo a um guia de estilo existente, bem como a este guia, se achar que a alteração beneficia todos os seus usos.
> #### "Discussões sobre o estilo são desnecessárias. Deve sempre haver um Guia de Estilo e você deve segui-lo."
> [_Rebecca Murphey_](https://rmurphey.com)
### 0.2 Toda estrutura, assets e código em qualquer projeto Unreal Engine 4 devem parecer que foram criados por uma única pessoa, não importa quantas pessoas contribuíram.
Mudar de um projeto para outro não deve causar uma reaprendizagem de estilo e estrutura. A conformidade com um Guia de Estilo remove suposições e ambigüidades desnecessárias.
Também permite uma criação e manutenção mais produtivas, pois não é necessário pensar no estilo. Simplesmente siga as instruções. Este guia de estilo foi escrito com as práticas recomendadas em mente, o que significa que, ao seguir este guia de estilo, você também minimizará problemas difíceis de rastrear.
### 0.3 Amigos não deixam amigos terem estilo ruim.
Se você vir alguém trabalhando contra um guia de estilo ou sem nenhum guia de estilo, tente corrigi-lo.
Ao trabalhar em uma equipe ou discutir em uma comunidade, como a [Unreal Slackers](http://join.unrealslackers.org/), é muito mais fácil ajudar e pedir ajuda quando as pessoas são consistentes. Ninguém gosta de ajudar a desemaranhar o "espaguete" do Blueprint de alguém ou lidar com assets que tenham nomes que eles não conseguem entender.
Se você está ajudando alguém cujo trabalho segue um Guia de Estilo diferente, mas consistente e lógico, você deve ser capaz de se adaptar a ele. Se eles não estiverem de acordo com nenhum Guia de Estilo, indique-os aqui.
### 0.4 Uma equipe sem um Guia de Estilo não é a minha equipe.
Ao ingressar em uma equipe Unreal Engine 4, uma de suas primeiras perguntas deve ser "Você tem um Guia de Estilo?". Se a resposta for não, você deve duvidar da capacidade deles de trabalhar em equipe.
### 0.5 Não quebre a lei
A Gamemakin LLC não é composta por advogados, mas não introduza ações e comportamentos ilegais em um projeto, incluindo, mas não se limitando a:
* Não distribua conteúdo para o qual você não tem os direitos de distribuição
* Não infrinja o material protegido por direitos autorais ou marca registrada de outra pessoa
* Não roube conteúdo
* Siga as restrições de licenciamento de conteúdo, por exemplo atributo quando as atribuições são necessárias
## 00. Opiniões Globalmente Impostas
@TODO: Faça esta a Seção 1 e atualize este documento de acordo. Ou talvez não?
### 00.1 Caracteres Proibidos
#### Identifiers
Em qualquer `Identifier` de qualquer tipo, **nunca** use o seguinte, a menos que seja obrigado:
* Espaço em branco de qualquer tipo
* Barras invertidas `\`
* Símbolos e.x. `#!@$%`
* Qualquer caractere Unicode
Um `Identifier` deve ter apenas os seguintes caracteres, quando possível (expressão regular `[A-Za-z0-9_]+`)
* ABCDEFGHIJKLMNOPQRSTUVWXYZ
* abcdefghijklmnopqrstuvwxyz
* 1234567890
* _ (moderadamente)
O motivo para isso é que garantirá a maior compatibilidade de todos os dados em todas as plataformas em todas as ferramentas e ajudará a evitar o tempo de inatividade devido ao tratamento potencialmente incorreto de caracteres para identificadores em códigos que você não controla.
## Índice
> 1. [Convenções de nomenclatura de assets](#anc)
> 1. [Estrutura de Diretório](#structure)
> 1. [Blueprints](#bp)
> 1. [Static Meshes](#s)
> 1. [Particle Systems](#ps)
> 1. [Levels / Maps](#levels)
> 1. [Textures](#textures)
## 1. Convenções de Nomenclatura de Assets
As convenções de nomenclatura devem ser tratadas como lei. Um projeto que está em conformidade com uma convenção de nomenclatura pode ter seus assets gerenciados, pesquisados, analisados e mantidos com uma facilidade incrível.
Geralmente são prefixadas com um acrônimo do tipo de asset seguido por um sublinhado (_).
### 1.1 Nome Base do Asset - `Prefixo_NomeBaseDoAsset_Variante_Sufixo`
Todos os assets devem ter um _Nome Base do Asset_. Um nome de asset básico representa um agrupamento lógico de assets relacionados. Qualquer asset que faça parte deste grupo lógico deve seguir o padrão de `Prefixo_NomeBaseDoAsset_Variante_Sufixo`.
Mantendo o padrão `Prefixo_NomeBaseDoAsset_Variante_Sufixo` em mente e usar o bom senso geralmente é suficiente para garantir bons nomes de assets. Aqui estão algumas regras detalhadas sobre cada elemento.
`Prefixo` e `Sufixo` devem ser determinados pelo tipo de asset por meio do seguinte tabelas de [Modificador do Nome do Asset](#asset-name-modifiers).
`NomeBaseDoAsset` deve ser determinado por um nome curto e facilmente reconhecível relacionado ao contexto desse grupo de assets. Por exemplo, se você tivesse um personagem chamado Bob, todos os assets de Bob teriam o `NomeBaseDoAsset` de `Bob`.
Para variações únicas e específicas de assets, `Variante` é um nome curto e facilmente reconhecível que representa o agrupamento lógico de assets que são um subconjunto do nome de base de um asset. Por exemplo, se Bob tinha várias skins, essas skins ainda deveriam usar `Bob` assim como `NomeBaseDoAsset` mas inclua um reconhecível `Variante`. Uma skin 'Evil' seria referida como `Bob_Evil` e uma skin 'Retro' seria referida como `Bob_Retro`.
Para variações únicas, mas genéricas de assets, `Variante` é um número de dois dígitos começando em `01`. Por exemplo, se você tem um Ambient Designer gerando rochas indefinidas, eles seriam nomeadas `Rocha_01`, `Rocha_02`, `Rocha_03`, etc. Exceto em raras exceções, você nunca deve exigir um número de variante de três dígitos. Se você tiver mais de 100 assets, deve considerar organizá-los com nomes de base diferentes ou usando vários nomes de variantes.
Dependendo de como suas variantes de assets são feitas, você pode encadear nomes de variantes. Por exemplo, se você estiver criando assets de piso para um projeto Arch Viz, você deve usar o nome de base `Piso` com variantes em cadeia, como `Piso_Marmore_01`, `Piso_Bordo_01`, `Piso_Tile_Quadrados_01`.
#### 1.1 Exemplos
##### 1.1e1 Bob
| Tipo de Asset | Nome do Asset |
| ----------------------- | ---------------------------------------------------------- |
| Skeletal Mesh | SK_Bob |
| Material | M_Bob |
| Texture (Diffuse/Albedo)| T_Bob_D |
| Texture (Normal) | T_Bob_N |
| Texture (Evil Diffuse) | T_Bob_Evil_D |
##### 1.1e2 Rocha
| Tipo de Asset | Nome do Asset |
| ----------------------- | ---------------------------------------------------------- |
| Static Mesh (01) | S_Rocha_01 |
| Static Mesh (02) | S_Rocha_02 |
| Static Mesh (03) | S_Rocha_03 |
| Material | M_Rocha |
| Material Instance (Neve)| MI_Rocha_Neve |
### 1.2 Modificadores de Nome de Asset
Ao nomear um asset, use essas tabelas para determinar o prefixo e sufixo a ser usado com ele [Nome Base do Asset](#base-asset-name).
#### Sections
> 1.2.1 [Mais comum](#anc-common)
> 1.2.2 [Animações](#anc-animations)
> 1.2.3 [Inteligência Artificial](#anc-ai)
> 1.2.4 [Blueprints](#anc-bp)
> 1.2.5 [Materials](#anc-materials)
> 1.2.6 [Textures](#anc-textures)
> 1.2.7 [Miscelâneas](#anc-misc)
> 1.2.8 [Paper 2D](#anc-paper2d)
> 1.2.9 [Física](#anc-physics)
> 1.2.10 [Som](#anc-sounds)
> 1.2.11 [Interface de Usuário](#anc-ui)
> 1.2.12 [Efeitos](#anc-effects)
#### 1.2.1 Mais comum
| Tipo de Asset | Prefixo | Suffixo | Notas |
| ----------------------- | ---------- | ---------- | -------------------------------- |
| Level / Mapas | | | [Deve estar em uma pasta chamada Maps.](#2.4) |
| Level (Persistente) | | _P | |
| Level (Audio) | | _Audio | |
| Level (Iluminação) | | _Lighting | |
| Level (Geometria) | | _Geo | |
| Level (Gameplay) | | _Gameplay | |
| Blueprint | BP_ | | |
| Material | M_ | | |
| Static Mesh | S_ | | Muitos usam SM_. Usamos S_. |
| Skeletal Mesh | SK_ | | |
| Texture | T_ | _? | Veja [Textures](#anc-textures) |
| Particle System | PS_ | | |
| Widget Blueprint | WBP_ | | |
#### 1.2.2 Animações
| Tipo de Asset | Prefixo | Suffixo | Notas |
| ----------------------- | ---------- | ---------- | -------------------------------- |
| Aim Offset | AO_ | | |
| Aim Offset 1D | AO_ | | |
| Animation Blueprint | ABP_ | | |
| Animation Composite | AC_ | | |
| Animation Montage | AM_ | | |
| Animation Sequence | A_ | | |
| Blend Space | BS_ | | |
| Blend Space 1D | BS_ | | |
| Level Sequence | LS_ | | |
| Morph Target | MT_ | | |
| Paper Flipbook | PFB_ | | |
| Rig | Rig_ | | |
| Skeletal Mesh | SK_ | | |
| Skeleton | SKEL_ | | |
### 1.2.3 Inteligência Artificial
| Tipo de Asset | Prefixo | Suffixo | Notas |
| ----------------------- | ---------- | ---------- | -------------------------------- |
| AI Controller | AIC_ | | |
| Behavior Tree | BT_ | | |
| Blackboard | BB_ | | |
| Decorator | BTDecorator_ | | |
| Service | BTService_ | | |
| Task | BTTask_ | | |
| Environment Query | EQS_ | | |
| EnvQueryContext | EQS_ | Contexto | |
### 1.2.4 Blueprints
| Tipo de Asset | Prefixo | Suffixo | Notas |
| ----------------------- | ---------- | ---------- | -------------------------------- |
| Blueprint | BP_ | | |
| Blueprint Component | BP_ | Component | E.x. BP_InventoryComponent |
| Blueprint Function Library | BPFL_ | | |
| Blueprint Interface | BPI_ | | |
| Blueprint Macro Library | BPML_ | | Não use bibliotecas de macro, se possível. |
| Enumeration | E | | Sem sublinhado. |
| Structure | F or S | | Sem sublinhado. |
| Tutorial Blueprint | TBP_ | | |
| Widget Blueprint | WBP_ | | |
### 1.2.5 Materials
| Tipo de Asset | Prefixo | Suffixo | Notas |
| ----------------------------- | ---------- | ---------- | -------------------------------- |
| Material | M_ | | |
| Material (Post Process) | PP_ | | |
| Material Function | MF_ | | |
| Material Instance | MI_ | | |
| Material Parameter Collection | MPC_ | | |
| Subsurface Profile | SP_ | | |
| Physical Materials | PM_ | | |
| Decal | M_, MI_ | _Decal | |
### 1.2.6 Textures
| Tipo de Asset | Prefixo | Suffixo | Notas |
| ----------------------- | ---------- | ---------- | -------------------------------- |
| Texture | T_ | | |
| Texture (Diffuse/Albedo/Base Color)| T_ | _D | |
| Texture (Normal) | T_ | _N | |
| Texture (Roughness) | T_ | _R | |
| Texture (Alpha/Opacity) | T_ | _A | |
| Texture (Ambient Occlusion) | T_ | _O | |
| Texture (Bump) | T_ | _B | |
| Texture (Emissive) | T_ | _E | |
| Texture (Mask) | T_ | _M | |
| Texture (Specular) | T_ | _S | |
| Texture (Metallic) | T_ | _M | |
| Texture (Packed) | T_ | _* | Veja as notas abaixo sobre [pacotes](#anc-textures-packing). |
| Texture Cube | TC_ | | |
| Media Texture | MT_ | | |
| Render Target | RT_ | | |
| Cube Render Target | RTC_ | | |
| Texture Light Profile | TLP | | |
#### 1.2.6.1 Pacote de textura
É uma prática comum compactar várias camadas de dados de textura em uma única textura. Um exemplo disso é agregar "Emissive", "Roughness", "Ambient Occlusion" juntos como os canais Vermelho, Verde e Azul de uma textura, respectivamente. Para determinar o sufixo, basta empilhar as letras de sufixo fornecidas de cima, e.g. `_ERO`.
> É geralmente aceitável incluir uma camada Alfa/Opacidade no canal Alfa de Difusão/Albedo e, como essa é uma prática comum, adicionar `A` ao sufixo` _D` é opcional.
Englobar 4 canais de dados em uma textura (RGBA) não é recomendado, exceto para uma máscara Alfa/Opacidade no canal Alfa de Difusão/Albedo, pois uma textura com um canal alfa incorre em mais sobrecarga do que uma sem.
### 1.2.7 Miscelâneas
| Tipo de Asset | Prefixo | Suffixo | Notas |
| -------------------------- | ---------- | ---------- | -------------------------------- |
| Animated Vector Field | VFA_ | | |
| Camera Anim | CA_ | | |
| Color Curve | Curve_ | _Color | |
| Curve Table | Curve_ | _Table | |
| Data Asset | *_ | | O prefixo deve ser baseado na classe. |
| Data Table | DT_ | | |
| Float Curve | Curve_ | _Float | |
| Foliage Type | FT_ | | |
| Force Feedback Effect | FFE_ | | |
| Landscape Grass Type | LG_ | | |
| Landscape Layer | LL_ | | |
| Matinee Data | Matinee_ | | |
| Media Player | MP_ | | |
| Object Library | OL_ | | |
| Redirector | | | Estes devem ser consertados o mais rápido possível. |
| Sprite Sheet | SS_ | | |
| Static Vector Field | VF_ | | |
| Substance Graph Instance | SGI_ | | |
| Substance Instance Factory | SIF_ | | |
| Touch Interface Setup | TI_ | | |
| Vector Curve | Curve_ | _Vector | |
### 1.2.8 Paper 2D
| Tipo de Asset | Prefixo | Suffixo | Notas |
| ----------------------- | ---------- | ---------- | -------------------------------- |
| Paper Flipbook | PFB_ | | |
| Sprite | SPR_ | | |
| Sprite Atlas Group | SPRG_ | | |
| Tile Map | TM_ | | |
| Tile Set | TS_ | | |
### 1.2.9 Física
| Tipo de Asset | Prefixo | Suffixo | Notas |
| ----------------------- | ---------- | ---------- | -------------------------------- |
| Physical Material | PM_ | | |
| Physics Asset | PHYS_ | | |
| Destructible Mesh | DM_ | | |
### 1.2.10 Som
| Tipo de Asset | Prefixo | Suffixo | Notas |
| ----------------------- | ---------- | ---------- | -------------------------------- |
| Dialogue Voice | DV_ | | |
| Dialogue Wave | DW_ | | |
| Media Sound Wave | MSW_ | | |
| Reverb Effect | Reverb_ | | |
| Sound Attenuation | ATT_ | | |
| Sound Class | | | Sem prefixo/sufixo. Deve ser colocado em uma pasta chamada SoundClasses |
| Sound Concurrency | | _SC | Deve ter o nome de uma SoundClass |
| Sound Cue | A_ | _Cue | |
| Sound Mix | Mix_ | | |
| Sound Wave | A_ | | |
### 1.2.11 Interface de Usuário
| Tipo de Asset | Prefixo | Suffixo | Notas |
| ----------------------- | ---------- | ---------- | -------------------------------- |
| Font | Font_ | | |
| Slate Brush | Brush_ | | |
| Slate Widget Style | Style_ | | |
| Widget Blueprint | WBP_ | | |
### 1.2.12 Efeitos
| Tipo de Asset | Prefixo | Suffixo | Notas |
| ----------------------- | ---------- | ---------- | -------------------------------- |
| Particle System | PS_ | | |
| Material (Post Process) | PP_ | | |
**[⬆ Voltar ao topo](#table-of-contents)**
## 2. Estrutura do Diretório de Conteúdo
Tão importante quanto os nomes de assets, o estilo da estrutura de diretório de um projeto deve ser considerado lei. As convenções de nomenclatura de assets e a estrutura do diretório de conteúdo andam de mãos dadas, e a violação de qualquer uma delas causa um caos desnecessário.
Existem várias maneiras de definir o conteúdo de um projeto UE4. Nesse estilo, usaremos uma estrutura que depende mais dos recursos de filtragem e pesquisa do Navegador de Conteúdo para aqueles que trabalham com assets para encontrar assets de um tipo específico, em vez de outra estrutura comum que agrupa tipos de assets com pastas.
> Se você estiver usando o prefixo [convenção de nomenclatura] (# 1.2) acima, usar pastas para conter assets de tipos semelhantes, como `Meshes`,` Textures` e `Materials` é uma prática redundante, pois os tipos de assets já são classificados por prefixo, bem como podem ser filtrado no Navegador de Conteúdo.
### 2e1 Exemplo de Estrutura de Conteúdo do Projeto
Os motivos para essa estrutura estão listados nas subseções a seguir.
### Seções
> 2.1 [Nomes de pasta](#structure-folder-names)
> 2.2 [Pasta de Nível Superior](#structure-top-level)
> 2.3 [Pastas de desenvolvedor](#structure-developers)
> 2.4 [Maps](#structure-maps)
> 2.5 [Core](#structure-core)
> 2.6 [`Assets` e `AssetTypes`](#structure-assettypes)
> 2.7 [Conjuntos Grandes](#structure-large-sets)
> 2.8 [Biblioteca de Materiais](#structure-material-library)
### 2.1 Nomes de pasta
Essas são regras comuns para nomear qualquer pasta na estrutura de conteúdo.
#### 2.1.1 Sempre use PascalCase[*](#terms-cases)
PascalCase refere-se a iniciar um nome com uma letra maiúscula e, em vez de usar espaços, todas as palavras seguintes também começam com uma letra maiúscula. Por exemplo, `DesertEagle`, `RocketPistol`, e `UmaSerieDePalavras`.
Veja [Casos](#terms-cases).
#### 2.1.2 Nunca Use Espaços
Reforçando [2.1.1](#2.1.1), nunca use espaços. Os espaços podem fazer com que várias ferramentas de engenharia e processos em lote falhem. Idealmente, a raiz do seu projeto também não deve contém espaços e está localizada em algum lugar como `D:\Project` em vez de `C:\Users\My Name\My Documents\Unreal Projects`.
#### 2.1.3 Nunca Use Caracteres Unicode e Outros Símbolos
Se um dos personagens do jogo se chama 'Zoë', o nome da pasta deve ser `Zoe`. Caracteres Unicode podem ser piores do que [Espaços](#2.1.2) para a ferramenta de engenharia e algumas partes do UE4 que também não oferecem suporte a caracteres Unicode em caminhos.
Relacionado a isso, se o seu projeto tiver [problemas inexplicáveis](https://answers.unrealengine.com/questions/101207/undefined.html) e o nome de usuário do seu computador tem um caractere Unicode (ou seja, seu nome é `Zoë`), qualquer projeto localizado na pasta `My Documents` sofrerá com esse problema. Freqüentemente, mover seu projeto para outra pasta como `D:\Project` corrigirá esses problemas.
Usando outros caracteres fora `a-z`, `A-Z`, e `0-9` como `@`, `-`, `_`, `,`, `*`, e `#` também pode levar a problemas inesperados e difíceis de rastrear em outras plataformas, source controls e ferramentas de engenharia mais fracas.
### 2.2 Use Uma Pasta de Nível Superior Para Assets Específicos do Projeto
Todos os assets de um projeto devem existir em uma pasta com o nome do projeto. Por exemplo, se o nome do seu projeto for 'Generic Shooter', _todo_ todo o seu conteúdo deve existir em `Content/GenericShooter`.
> A pasta `Developers` não é para assets dos quais seu projeto depende e, portanto, não é específica do projeto. Consulte [Pastas de desenvolvedor] (# 2.3) para obter detalhes sobre isso.
Existem várias razões para esta abordagem.
#### 2.2.1 Sem Assets Globais
Freqüentemente, nos guias de estilo de código está escrito que você não deve poluir o namespace global e isso segue o mesmo princípio. Quando assets podem existir fora de uma pasta de projeto, geralmente se torna muito mais difícil impor um layout de estrutura estrito, pois assets que não estão em uma pasta encorajam o mau comportamento de não ter que organiza-los.
Todo asset deve ter um propósito, caso contrário, ele não pertence a um projeto. Se um asset é um teste experimental e não deve ser usado pelo projeto, deve ser colocado em uma pasta [`Developer`](#2.3).
#### 2.2.2 Reduza Conflitos de Migração
Ao trabalhar em vários projetos, é comum que uma equipe copie assets de um projeto para outro, caso tenham feito algo útil para ambos. Quando isso ocorre, a maneira mais fácil de realizar a cópia é usar a funcionalidade Migrar do navegador de conteúdo, pois ela copiará não apenas o asset selecionado, mas todas as suas dependências.
Essas dependências podem facilmente causar problemas. Se os assets de dois projetos não tiverem uma pasta de nível superior e acontecerem de terem assets nomeados de forma semelhante ou já migrados anteriormente, uma nova migração pode apagar acidentalmente quaisquer alterações nos assets existentes.
Esse também é o principal motivo pelo qual a equipe do Marketplace da Epic aplica a mesma política para assets enviados.
Após uma migração, a fusão segura de assets pode ser feita usando a ferramenta 'Substituir referências' no navegador de conteúdo com a clareza adicional de assets não pertencentes à pasta de nível superior de um projeto e claramente aguardando uma fusão. Depois que os assets são mesclados e totalmente migrados, não deve haver outra pasta de nível superior em sua árvore de conteúdo. Este método é _100% _ garantido para tornar todas as migrações que ocorrerem completamente seguras.
##### 2.2.2e1 Exemplo de Master Material
Por exemplo, digamos que você criou um Master Material em um projeto que gostaria de usar em outro projeto, então migrou esse asset. Se este asset não estiver em uma pasta de nível superior, pode ter um nome como `Content/MaterialLibrary/M_Master`. Se o projeto de destino ainda não tiver um Master Material, isso deve funcionar sem problemas.
Conforme o trabalho em um ou ambos os projetos progride, seus respectivos Master Material podem ser alterados para serem adaptados para seus projetos específicos devido ao curso de desenvolvimento normal.
O problema surge quando, por exemplo, um artista para um projeto criou um bom conjunto modular genérico de static meshes e alguém deseja incluir esse conjunto de static meshes no segundo projeto. Se o artista que criou os recursos usou Material Instances com base em `Content/MaterialLibrary/M_Master` conforme são instruídos, quando uma migração é realizada, há uma grande chance de conflito para o asset migrado anteriormente `Content/MaterialLibrary/M_Master`.
Esse problema pode ser difícil de prever e de explicar. A pessoa que migra as static meshes pode não ser a mesma pessoa que está familiarizada com o desenvolvimento de ambos os Master Material do projeto e pode nem mesmo estar ciente de que as static meshes em questão dependem de Material Instances que, então, dependem do Master Material. A ferramenta Migrar requer que toda a cadeia de dependências funcione, no entanto, será obrigada a pegar `Content/MaterialLibrary/M_Master` quando ela copia esses assets para o outro projeto e sobrescrever o asset existente.
É neste ponto que se os Master Materials para ambos os projetos forem incompatíveis de _qualquer maneira_, você corre o risco de quebrar possivelmente toda a biblioteca de Materials de um projeto, bem como quaisquer outras dependências que já possam ter sido migradas, simplesmente porque os assets não foram armazenados em uma pasta de nível superior. A simples migração de static meshes agora se torna uma tarefa muito ruim.
#### 2.2.3 Amostras, Modelos e Conteúdos do Marketplace Estão Livres de Riscos
Uma extensão para [2.2.2](#2.2.2), se um membro da equipe decidir adicionar conteúdo de amostra, arquivos de modelo ou assets que comprou no Marketplace, é garantido, desde que a pasta de nível superior do seu projeto tenha um nome exclusivo, que esses novos assets não interferirão em seu projeto.
Você não pode confiar que o conteúdo do marketplace está em total conformidade com a [regra de pasta de nível superior] (# 2.2). Existem muitos assets que têm a maior parte de seu conteúdo em uma pasta de nível superior, mas também possuem Conteúdo de Amostra da Epic possivelmente modificados, bem como arquivos de nível poluindo a pasta global `Content`.
Ao aderir a [2.2](#2.2), o pior conflito de marketplace que você pode ter é se dois assets de marketplace tiverem o mesmo Conteúdo de Amostra da Epic. Se todos os seus assets estiverem em uma pasta específica do projeto, incluindo conteúdo de amostra que você pode ter movido para a sua pasta, seu projeto nunca será quebrado.
#### 2.2.4 DLC, Subprojetos e Patches São Facilmente Mantidos
Se o seu projeto planeja lançar DLC ou tem vários subprojetos associados a ele que podem ser migrados ou simplesmente não preparados em uma construção, os assets relacionados a esses projetos devem ter sua própria pasta de conteúdo de nível superior separada. Isso torna muito mais fácil cozinhar DLC separados do conteúdo do projeto principal. Os subprojetos também podem ser migrados para dentro e para fora com o mínimo de esforço. Se você precisar alterar um material de um assets ou adicionar algum comportamento de substituição de asset muito específico em um patch, você pode facilmente colocar essas alterações em uma pasta de patch e trabalhar com segurança sem a chance de quebrar o projeto principal.
### 2.3 Use a Pasta Developers Para Testes Locais
Durante o desenvolvimento de um projeto, é muito comum que os membros da equipe tenham uma espécie de 'sandbox' onde podem experimentar livremente sem arriscar o projeto principal. Como esse trabalho pode estar em andamento, esses membros da equipe podem querer colocar seus assets em um servidor de source control do projeto. Nem todas as equipes exigem o uso de pastas Developers, mas aquelas que as usam costumam ter um problema comum com assets enviados ao source control.
É muito fácil para um membro da equipe usar acidentalmente assets que não estão prontos para uso, o que causará problemas quando esses assets forem removidos. Por exemplo, um artista pode estar iterando em um conjunto modular de static meshes e ainda trabalhando para obter o tamanho e o encaixe da grade corretos. Se um world designer ver esses assets na pasta principal do projeto, ele pode usá-los em um nível sem saber que podem estar sujeitos a mudanças e/ou remoções. Isso causa uma grande quantidade de retrabalho para todos na equipe resolverem.
Se esses assets modulares fossem colocados em uma pasta de desenvolvedor, o world designer nunca deveria ter tido um motivo para usá-los e todo o problema nunca aconteceria. O navegador de conteúdo tem opções de exibição específicas que ocultam as pastas do desenvolvedor (elas ficam ocultas por padrão), tornando impossível o uso acidental de assets do desenvolvedor em uso normal.
Assim que os recursos estiverem prontos para uso, o artista simplesmente precisa mover os recursos para a pasta específica do projeto e corrigir os redirecionadores. Isso é essencialmente 'promover' os assets do experimental para a produção.
### 2.4 Todo Arquivo de Mapa[*](#terms-level-map) Pertence a Uma Pasta Chamada Maps
Os arquivos de mapa são incrivelmente especiais e é comum que cada projeto tenha seu próprio sistema de nomenclatura de mapa, especialmente se eles trabalharem com subníveis ou níveis de streaming. Não importa qual sistema de organização de mapas está em vigor para o projeto específico, todos os níveis devem pertencer a `/Content/Project/Maps`.
Ser capaz de dizer a alguém para abrir um mapa específico sem ter que explicar onde ele está economiza muito tempo e melhora a 'qualidade de vida' em geral. É comum que os níveis estejam dentro de subpastas de `Maps`, tal como `Maps/Campaign1/` ou `Maps/Arenas`, mas o mais importante aqui é que todos eles existem dentro `/Content/Project/Maps`.
Isso também simplifica o trabalho de cozinhar para os engenheiros. Combinar os níveis de um processo de compilação pode ser extremamente frustrante se eles tiverem que vasculhar pastas arbitrárias. Se os mapas de uma equipe estão todos em um só lugar, é muito mais difícil acidentalmente não preparar um mapa em uma construção. Ele também simplifica os scripts de construção de iluminação, bem como os processos de controle de qualidade.
### 2.5 Use uma Pasta `Core` Para Blueprints Críticos e Outros Assets
Use a pasta`/Content/Project/Core` para assets que são absolutamente fundamentais para o funcionamento de um projeto. Por exemplo, `GameMode`, `Character`, `PlayerController`, `GameState`, `PlayerState`, base e os Blueprints relacionados devem residir aqui.
Isso cria uma mensagem muito clara "não toque nestes" para os outros membros da equipe. Os que não são engenheiros devem ter muito poucos motivos para entrar na pasta `Core`. Seguindo um bom estilo de estrutura de código, os designers devem fazer seus ajustes de jogabilidade em classes filhas que expõem a funcionalidade. Os world designers devem usar Blueprints pré-fabricados em pastas designadas em vez de abusar potencialmente das classes base.
Por exemplo, se o seu projeto requer "pickups" que podem ser colocados em um nível, deve existir uma classe de "pickup" base em `Core/Pickups` que define o comportamento básico para uma "pickup". Coletas específicas, como Health ou Ammo, devem existir em uma pasta como `/Content/Project/Placeables/Pickups/`. Os designers de jogos podem definir e ajustar opções nesta pasta da maneira que quiserem, mas não devem tocar `Core/Pickups` pois eles podem interromper involuntariamente "pickups" em todo o projeto.
### 2.6 Não Crie Pastas Chamadas `Assets` ou `AssetTypes`
#### 2.6.1 Criar uma pasta chamada `Assets` é redundante.
Todos assets são assets.
#### 2.6.2 Criar uma pasta chamada `Meshes`, `Textures`, ou `Materials` é redundante.
Todos os nomes de assets são nomeados com seu tipo de asset em mente. Essas pastas oferecem apenas informações redundantes e o uso dessas pastas pode ser facilmente substituído pelo sistema de filtragem robusto e fácil de usar que o Navegador de Conteúdo oferece.
Quer apenas ver static mesh em `Environment/Rocks/`? Basta ativar o filtro Static Mesh. Se todos os assets forem nomeados corretamente, eles também serão classificados em ordem alfabética, independentemente dos prefixos. Quer visualizar static meshes e skeletal meshes? Basta ligar os dois filtros. Isso elimina a necessidade de selecionar duas pastas com `Control-Click` na visualização em árvore do navegador de conteúdo.
> Isso também estende o nome do caminho completo de um asset para muito poucos benefícios. O prefixo `S_` para uma static mesh tem apenas dois caracteres, enquanto `Meshes/`tem sete caracteres.
Não fazer isso também previne de alguém colocar uma static mesh ou uma textura em uma pasta `Materials`.
### 2.7 Conjunto de Assets Muito Grandes Tem Seu Próprio Layout de Pasta
Isso pode ser visto como uma pseudo-exceção para [2.6](#2.6).
Existem certos tipos de assets que possuem um grande volume de arquivos relacionados, onde cada asset tem uma finalidade única. Os dois mais comuns são assets de animação e áudio. Se você tiver mais de 15 desses assets que pertencem um ao outro, eles devem estar juntos.
Por exemplo, as animações que são compartilhadas por vários personagens devem estar em `Characters/Common/Animations` e pode ter subpastas como `Locomotion` ou `Cinematic`.
> Isso não se aplica a assets como texturas e materiais. É comum que uma pasta `Rochas` tenha uma grande quantidade de texturas se houver uma grande quantidade de pedras, no entanto, essas texturas geralmente estão relacionadas apenas a algumas pedras específicas e devem ser nomeadas apropriadamente. Mesmo que essas texturas sejam parte de uma [Biblioteca de Materials](#2.8).
### 2.8 `Biblioteca de Materials`
Se o seu projeto faz uso de master materials, layered materials, ou qualquer forma de materiais reutilizáveis ou texturas que não pertençam a nenhum subconjunto de assets, esses assets devem estar localizados em `Content/Project/MaterialLibrary`.
Desta forma materials 'global' têm um lugar e são facilmente localizados.
> Isso também torna incrivelmente fácil aplicar uma política de 'use material instances only' dentro de um projeto. Se todos os artistas e assets deveriam estar usando instâncias de material, então os únicos assets materials regulares que deveriam existir estão dentro desta pasta. Você pode verificar isso facilmente procurando por base materials em qualquer pasta que não seja o `MaterialLibrary`.
A `MaterialLibrary` não precisa consistir puramente em materials. Texturas de utilitários compartilhados, funções materiais e outras coisas dessa natureza devem ser armazenadas aqui também em pastas que indicam sua finalidade. Por exemplo, texturas de ruído genéricas devem estar localizadas em `MaterialLibrary/Utility`.
Qualquer material de teste ou depuração deve estar dentro de `MaterialLibrary/Debug`. Isso permite que os materiais de depuração sejam facilmente retirados de um projeto antes do envio e torna incrivelmente aparente se os assets de produção os estão usando se forem mostrados erros de referência.
### 2.9 Sem Pastas Vazias
Simplesmente não deve haver pastas vazias. Eles confundem o navegador de conteúdo.
Se você descobrir que o navegador de conteúdo tem uma pasta vazia que não pode ser excluída, faça o seguinte:
1. Certifique-se de usar o controle de origem.
1. Execute imediatamente Fix Up Redirectors em seu projeto.
1. Navegue até a pasta no disco e exclua os assets dentro dela.
1. Feche o editor.
1. Certifique-se de que seu estado de source control está sincronizado (ou seja, se estiver usando Perforce, execute um Reconcile Offline Work em seu diretório de conteúdo)
1. Abra o editor. Confirme se tudo ainda está funcionando conforme o esperado. Caso contrário, reverta, descubra o que deu errado e tente novamente.
1. Certifique-se de que a pasta já foi removida.
1. Envie as alterações para o source control.
**[⬆ Voltar ao topo](#table-of-contents)**
## 3. Blueprints
Esta seção se concentrará nas classes do Blueprint e em seus aspectos internos. Quando possível, as regras de estilo estão em conformidade com [Epic's Coding Standard](https://docs.unrealengine.com/latest/INT/Programming/Development/CodingStandard).
Lembre-se: Blueprinting comporta mal os erros, cuidado! (Frase por [KorkuVeren](http://github.com/KorkuVeren))
### Sections
> 3.1 [Compilando](#bp-compiling)
> 3.2 [Variáveis](#bp-vars)
> 3.3 [Funções](#bp-functions)
> 3.4 [Gráficos](#bp-graphs)
### 3.1 Compilando
Todos os blueprints devem ser compilados com nenhum aviso e nenhum erro. Você deve corrigir os avisos e erros do blueprint imediatamente, pois eles podem rapidamente se transformar em um comportamento inesperado muito assustador.
*Não* envie projetos corrompidos ao source control. Se você deve armazená-los no source control, arquive-os.
Projetos corrompidos podem causar problemas que se manifestam de outras maneiras, como referências quebradas, comportamento inesperado, falhas de cozimento e recompilação desnecessária frequente. Um projeto quebrado tem o poder de quebrar todo o seu jogo.
### 3.2 Variáveis
As palavras `variable` e `property` podem ser usadas alternadamente.
#### Seções
> 3.2.1 [Nomeação](#bp-vars)
> 3.2.2 [Editável](#bp-vars-editable)
> 3.2.3 [Categorias](#bp-vars-categories)
> 3.2.4 [Acesso](#bp-vars-access)
> 3.2.5 [Avançado](#bp-vars-advanced)
> 3.2.6 [Transiente](#bp-vars-transient)
> 3.2.7 [Config](#bp-vars-config)
#### 3.2.1 Nomenclatura
##### 3.2.1.1 Substantivos
Todos os nomes de variáveis que não são booleans devem ser substantivos claros, não ambíguos e descritivos.
##### 3.2.1.2 PascalCase
Todas as variáveis não booleanas devem estar na forma de [PascalCase](#terms-cases).
###### 3.2.1.2e Exemplos:
* `Score`
* `Kills`
* `TargetPlayer`
* `Range`
* `CrosshairColor`
* `AbilityID`
##### 3.2.1.3 Prefix `b` Para Boolean
Todos os booleans devem ser nomeados em PascalCase, mas prefixados com uma minúscula `b`.
Exemplo: Use `bDead` e `bEvil`, **não use** `Dead` ou `Evil`.
Editores Blueprint UE4 sabem não colocar o `b` em exibições user-friendly da variável.
##### 3.2.1.4 Nomes de Booleans
###### 3.2.1.4.1 Informações Gerais e Condições Independentes
Todos os booleans devem ser nomeados como adjetivos descritivos, quando possível, se representarem informações gerais. Não inclua palavras que expressem a variável como uma pergunta, como `Is`. Isso é reservado para funções.
Exemplo: Use `bDead` e `bHostile` **não use** `bIsDead` ou `bIsHostile`.
Tente não usar verbos como `bRunning`. Os verbos tendem a levar a estados complexos.
###### 3.2.1.4.2 Condições Complexas
Não use booleans para representar condições complexas e/ou dependentes. Isso torna a adição e remoção das condições complexas mais difíceis de ler. Em vez disso, use uma enumeração.
Exemplo: Ao definir uma arma, **não** use `bReloading` e `bEquipping` se uma arma não pode recarregar e ser equipada. Defina uma enumeração chamada `EWeaponState` e usar uma variável com este tipo chamada `WeaponState` em vez disso. Isso torna muito mais fácil adicionar novos estados às armas.
Exemplo: **Não** use `bRunning` se você também precisa de `bWalking` ou `bSprinting`. Isso deve ser definido como uma enumeração com nomes de estado claramente definidos.
##### 3.2.1.5 Contexto Deve Ser Considerado
Todos os nomes de variáveis não devem ser redundantes com seu contexto, pois todas as referências de variáveis no Blueprint sempre terão contexto.
###### 3.2.1.5e Exemplos:
Considere um Blueprint chamado `BP_PlayerCharacter`.
**Ruim**
* `PlayerScore`
* `PlayerKills`
* `MyTargetPlayer`
* `MyCharacterName`
* `CharacterSkills`
* `ChosenCharacterSkin`
Todas essas variáveis são nomeadas de forma redundante. Está implícito que a variável pertence ao `BP_PlayerCharacter` porque é o `BP_PlayerCharacter` que está definindo essas variáveis.
**Bom**
* `Score`
* `Kills`
* `TargetPlayer`
* `Name`
* `Skills`
* `Skin`
##### 3.2.1.6 _Não_ Inclua Nomes de Tipo Atômico
Variáveis atômicas ou primitivas são variáveis que representam dados em sua forma mais simples, como booleans, integers, floats e enumerações.
Strings e vectors são considerados atômicos em termos de estilo ao trabalhar com Blueprints, no entanto, eles não são tecnicamente atômicos.
> Enquanto vectors consiste de três floats, vectors muitas vezes podem ser manipulados como um todo, assim como rotators.
> _Não_ considere Text Variables como atômicas, elas estão escondendo a funcionalidade de localização. O tipo atômico de uma string de caracteres é `String`, não `Text`.
Variáveis atômicas não devem ter seu nome de tipo em seu nome.
Exemplo: Use `Score`, `Kills`, e `Description` **não use** `ScoreFloat`, `FloatKills`, `DescriptionString`.
A única exceção a esta regra é quando uma variável representa 'um número de' algo a ser contado _e_ quando usar um nome difícil de ler sem um tipo de variável.
Exemplo: Um gerador de cerca precisa gerar um número X de postes. Armazene X em `NumPosts` ou `PostsCount` em vez de `Posts` como `Posts` pode potencialmente ser lido como um Array de um tipo de variável chamado `Post`.
##### 3.2.1.7 Inclua Nomes de Tipo Não Atômico
Variáveis não atômicas ou complexas são variáveis que representam dados como uma coleção de variáveis atômicas. Structs, Classes, Interfaces, e primitivas with com comportamento oculto, como `Text` e `Name` todos se qualificam sob esta regra.
> Enquanto um Array de um tipo de variável atômica é uma lista de variáveis, Arrays não altera a 'atomicidade' de um tipo de variável.
Essas variáveis devem incluir seu nome de tipo, ainda considerando seu contexto.
Se uma classe possui uma instância de uma variável complexa, e.x. se um `BP_PlayerCharacter` possui um `BP_Hat`, deve ser armazenado como o tipo de variável, sem nenhuma modificação de nome.
Exemplo: Use `Hat`, `Flag`, e `Ability` **não use** `MyHat`, `MyFlag`, e `PlayerAbility`.
Se uma classe não possui o valor que uma variável complexa representa, você deve usar um substantivo junto com o tipo de variável.
Exemplo: Se um `BP_Turret` tem a capacidade de mirar um `BP_PlayerCharacter`, deve armazenar seu alvo como `TargetPlayer` como quando no contexto de `BP_Turret` deve ficar claro que é uma referência a outro tipo de variável complexa que não possui.
##### 3.2.1.8 Arrays
Arrays segue as mesmas regras de nomenclatura acima, mas deve ser nomeado como um substantivo no plural.
Exemplo: Use `Targets`, `Hats`, e `EnemyPlayers`, **não use** `TargetList`, `HatArray`, `EnemyPlayerArray`.
#### 3.2.2 Variáveis Editáveis
Todas as variáveis que são seguras para alterar o valor de para configurar o comportamento de um blueprint devem ser marcadas como `Editable`.
Por outro lado, todas as variáveis que não são seguras para alteração ou não devem ser expostas aos designers _não_ devem ser marcadas como editáveis, a menos que por razões de engenharia a variável deva ser marcada como `Expose On Spawn`.
Não marque variáveis arbitrariamente como `Editable`.
##### 3.2.2.1 Tooltips
Todas variáveis `Editable`, incluindo aqueles marcados como editáveis, apenas para que possam ser marcados como `Expose On Spawn`, deve ter uma descrição em seus campos de `Tooltip` que explique como a alteração desse valor afeta o comportamento do blueprint.
##### 3.2.2.2 Sliders e Intervalos de Valor
Todas variáveis `Editable` deve fazer uso de um slider e um intervalo de valor se houver um valor para o qual uma variável _não_ deve ser definida.
Exemplo: Um blueprint que gera postes de cerca pode ter uma variável editável chamada `PostsCount` e um valor de -1 não faria nenhum sentido. Use os campos de intervalo para marcar 0 como o mínimo.
Se uma variável editável é usada em um Construction Script, deve ter um "Slider Range" razoável definido para que alguém não possa acidentalmente atribuir a ele um grande valor que poderia travar o editor.
Um "Value Range" só precisa ser definido se os limites de um valor forem conhecidos. Enquanto um "Slider Range" evita entradas acidentais de um grande número, um indefinido "Value Range" permite que um usuário especifique um valor fora do "Slider Range" que pode ser considerado 'perigoso', mas ainda válido.
#### 3.2.3 Categorias
Se uma classe tem apenas um pequeno número de variáveis, as categorias não são obrigatórias.
Se uma class tem uma quantidade moderada de variáveis (5-10), todas variáveis `Editable` deve ter uma categoria não padrão atribuída. Uma categoria comum é `Config`.
Se uma class tem uma grande quantidade de variáveis, todas variáveis `Editable` deve ser categorizado em subcategorias usando a categoria `Config` como a categoria base. Variáveis não editáveis devem ser categorizadas em categorias descritivas que descrevem seu uso.
> Você pode definir subcategorias usando a barra vertical `|`, e.x. `Config | Animations`.
Exemplo: Um conjunto de variáveis de classe de arma pode ser organizado como:
|-- Config
| |-- Animations
| |-- Effects
| |-- Audio
| |-- Recoil
| |-- Timings
|-- Animations
|-- State
|-- Visuals
#### 3.2.4 Nível de acesso variável
Em C ++, as variáveis têm um conceito de nível de acesso. Público significa que qualquer código fora da classe pode acessar a variável. Protegido significa que apenas a classe e quaisquer classes filhas podem acessar essa variável internamente. Privado significa que apenas esta classe e nenhuma classe filha pode acessar esta variável.
Blueprints atualmente não tem um conceito definido de acesso protegido.
Trate a variável `Editable` como variáveis públicas. Trate as variáveis não editáveis como variáveis protegidas.
##### 3.2.4.1 Variáveis Privadas
A menos que se saiba que uma variável só deve ser acessada dentro da classe em que está definida e nunca em uma classe filha, não marque as variáveis como privadas. Até que as variáveis possam ser marcadas `protected`, reserve particular para quando você tiver certeza absoluta de que deseja restringir o uso de classes filhas.
#### 3.2.5 Display Avançado
Se uma variável deve ser editável, mas muitas vezes intocada, marque-a como `Advanced Display`. Isso torna a variável oculta, a menos que a seta de exibição avançada seja clicada.
Para encontrar a opção `Advanced Display`, ela é listada como uma variável avançada exibida na lista de detalhes da variável.
#### 3.2.6 Variáveis Transientes
Variáveis transientes são variáveis que não precisam ter seu valor salvo e carregado, e possuem um valor inicial igual a zero ou nulo. Isso é útil para referências a outros objetos e atores cujo valor não é conhecido até o tempo de execução. Isso evita que o editor salve uma referência a ele e acelera o salvamento e o carregamento da classe de blueprint.
Por causa disso, todas as variáveis transientes sempre devem ser inicializadas como zero ou nulas. Fazer o contrário resultaria em erros difíceis de depurar.
#### 3.2.8 Variáveis de configuração
Não use a flag `Config Variable`. Isso torna mais difícil para os designers controlar o comportamento do blueprint. Variáveis de configuração só devem ser usadas em C ++ para variáveis raramente alteradas. Pense neles como variáveis `Advanced Advanced Display`.
### 3.3 Functions, Events, e Event Dispatchers
Esta seção descreve como você deve criar functions, events, e event dispatchers. Tudo o que se aplica a funções também se aplica a events, salvo indicação contrária.
#### 3.3.1 Nomenclatura de função
A nomenclatura de functions, events, e event dispatchers são extremamente importante. Com base apenas no nome, certas suposições podem ser feitas sobre as funções. Por exemplo:
* É uma função "pure"?
* Está buscando informações de estado?
* É um handler?
* É um RPC?
* Qual é seu propósito?
Essas perguntas e muito mais podem ser respondidas quando as funções são nomeadas apropriadamente.
#### 3.3.1.1 Todas as Funções Devem Ser Verbos
Todas as funções e events realizam alguma forma de ação, seja para obter informações, calcular dados ou fazer algo explodir. Portanto, todas as funções devem começar com verbos. Eles devem ser redigidos no tempo presente sempre que possível. Eles também devem ter algum contexto sobre o que estão fazendo.
Funções `OnRep`, event handlers, e event dispatchers são uma exceção a esta regra.
Bons exemplos:
* `Fire` - Bom exemplo se estiver em uma classe de Personagem/Arma, pois tem contexto. Ruim se estiver em um Barril / Gramado / qualquer classe ambígua.
* `Jump` - Bom exemplo se em uma classe de Personagem, caso contrário, precisa de contexto.
* `Explode`
* `ReceiveMessage`
* `SortPlayerArray`
* `GetArmOffset`
* `GetCoordinates`
* `UpdateTransforms`
* `EnableBigHeadMode`
* `IsEnemy` - ["Is" é um verbo.](http://writingexplained.org/is-is-a-verb)
Maus exemplos:
* `Dead` - Está morto? Vai morrer?
* `Rock`
* `ProcessData` - Ambíguas, essas palavras não significam nada.
* `PlayerState` - Os substantivos são ambíguos.
* `Color` - Verbo sem contexto ou substantivo ambíguo.
#### 3.3.1.2 Funções Com Propriedade "RepNotify" Sempre `OnRep_Variable`
Todas as funções replicadas com variáveis de notificação devem ter o formato `OnRep_Variable`. Isso é forçado pelo editor Blueprint. Se você está escrevendo um C ++ `OnRep` no entanto, ele também deve seguir esta convenção ao expô-lo para Blueprints.
#### 3.3.1.3 Funções de Informação Que Retornam Bool Devem Fazer Perguntas
Ao escrever uma função que não altera o estado ou modifica qualquer objeto e é puramente para: obter informações, estado ou calcular um valor sim/não. Ela deve fazer uma pergunta. Isso também deve seguir [a regra do verbo](#bp-funcs-naming-verbs).
Isso é extremamente importante, pois se uma pergunta não for feita, pode-se presumir que a função executa uma ação e está retornando se essa ação foi bem-sucedida.
Bons exemplos:
* `IsDead`
* `IsOnFire`
* `IsAlive`
* `IsSpeaking`
* `IsHavingAnExistentialCrisis`
* `IsVisible`
* `HasWeapon` - ["Has" é um verbo.](http://grammar.yourdictionary.com/parts-of-speech/verbs/Helping-Verbs.html)
* `WasCharging` - ["Was" é pretérito de "be".](http://grammar.yourdictionary.com/parts-of-speech/verbs/Helping-Verbs.html) Use "was" quando se refere a 'quadro anterior' ou 'estado anterior'.
* `CanReload` - ["Can" é um verbo.](http://grammar.yourdictionary.com/parts-of-speech/verbs/Helping-Verbs.html)
Maus exemplos:
* `Fire` - Está em chamas? Vai atirar? Atire?
* `OnFire` - Pode ser confundido com o event dispatcher para disparo.
* `Dead` - Está morto? Vai morrer?
* `Visibility` - É visível? Definir visibilidade? Uma descrição das condições de vôo?
#### 3.3.1.4 Event Handlers e Dispatchers Deve Começar Com `On`
Qualquer função que lida com um event ou despacha um event deve começar com `On` e continue a seguir [a regra do verbo](#bp-funcs-naming-verbs). O verbo pode mover-se para o final, no entanto, se o tempo passado for melhor lido.
[Colocações](http://dictionary.cambridge.org/us/grammar/british-grammar/about-words-clauses-and-sentences/collocation) da palavra `On` estão isentos de seguir a regra do verbo.
`Handle` não é permitido. É 'irreal' usar `On` ao invés de `Handle`, enquanto outras estruturas podem preferir usar `Handle` ao invés de `On`.
Bons exemplos:
* `OnDeath` - Colocação comum em jogos
* `OnPickup`
* `OnReceiveMessage`
* `OnMessageRecieved`
* `OnTargetChanged`
* `OnClick`
* `OnLeave`
Maus exemplos:
* `OnData`
* `OnTarget`
* `HandleMessage`
* `HandleDeath`
#### 3.3.1.5 Chamadas de Procedimento Remoto (RPC) Devem Ser Prefixadas com Destino
Sempre que um RPC é criado, deve ser prefixado com um `Server`, `Client`, ou `Multicast`. Sem exceções.
Após o prefixo, siga todas as outras regras relacionadas à nomenclatura de funções.
Bons exemplos:
* `ServerFireWeapon`
* `ClientNotifyDeath`
* `MulticastSpawnTracerEffect`
Maus exemplos:
* `FireWeapon` - Não indica que seja algum tipo de RPC.
* `ServerClientBroadcast` - Confuso.
* `AllNotifyDeath` - Use `Multicast`, nunca `All`.
* `ClientWeapon` - Sem verb, ambíguo.
#### 3.3.2 Todas as Funções Devem Ter "Return Nodes"
Todas as funções devem ter return nodes, sem exceções.
Return nodes significam que uma função concluiu sua execução. Como os projetos podem ser preenchidos com `Sequence`, `ForLoopWithBreak`, e reroute nodes reversos, fluxo de execução explícito é importante para leitura, manutenção e depuração mais fáceis dos mesmos.
O compilador Blueprint é capaz de seguir o fluxo de execução e irá avisá-lo se houver um branch de seu código com um retorno não tratado ou fluxo incorreto se você usar return nodes.
Em situações como quando um programador pode adicionar um alfinete a um Sequence node ou adicionar lógica após a conclusão de um "loop for", mas a iteração do loop pode retornar mais cedo, o que geralmente pode resultar em um erro acidental no fluxo de código. Os avisos do compilador Blueprint alertarão a todos sobre esses problemas imediatamente.
#### 3.3.3 Nenhuma Função Deve Ter Mais de 50 Nós
Simplesmente, nenhuma função deve ter mais de 50 nós. Qualquer função desse tamanho deve ser dividida em funções menores para facilitar a leitura e manutenção.
Os seguintes nós não são contados, pois são considerados como não aumentando a complexidade da função:
* Comentários
* Route
* Cast
* Obtendo uma Variable
* Quebrando um Struct
* Funções Entry
* Self
#### 3.3.4 Todas As Funções Públicas Devem Ter Uma Descrição
Esta regra se aplica mais a blueprints públicas ou do marketplace, para que outras pessoas possam navegar e consumir sua API de blueprint com mais facilidade.
Simplesmente, qualquer função que tenha um especificador de acesso de Public deve ter sua descrição preenchida.
#### 3.3.5 Todas Funções de Plugin 'Static' e `BlueprintCallable` Personalizadas Deve Ser Categorizado Pelo Nome do Plugin
Se o seu projeto inclui um plugin que define funções `static` `BlueprintCallable`, ele devem ter sua categoria definida para o nome do plugin ou uma categoria de subconjunto do nome do plugin.
Por exemplo, `Zed Camera Interface` ou `Zed Camera Interface | Image Capturing`.
### 3.4 Gráficos Blueprint
Esta seção cobre coisas que se aplicam a todos os gráficos do Blueprint.
#### 3.4.1 Sem "Espaguete"
Os fios devem ter começo e fim claros. Você nunca deve ter que desembaraçar mentalmente os fios para dar sentido a um gráfico. Muitas das seções a seguir são dedicadas à redução do "espaguete".
#### 3.4.2 Alinhe Fios, Não Nodes
Sempre alinhe os fios, não os nodes. Você nem sempre pode controlar o tamanho e a localização do pino em um node, mas você sempre pode controlar a localização de um node e, assim, controlar os fios. Fios retos fornecem fluxo linear claro. Fios ondulados desgastam muito a mente. Você pode endireitar os fios usando o comando "Straighten Connections" com os nodes BP selecionados. Atalho: Q
Bom exemplo: os topos dos nodes são escalonados para manter uma linha executiva branca perfeitamente reta.
Mau exemplo: Os topos dos nodes são alinhados, criando uma linha executiva branca ondulada.
Exemplo aceitável: Certos nodes podem não cooperar, não importa como você usa as ferramentas de alinhamento. Nessa situação, tente minimizar a oscilação trazendo o node para mais perto.
#### 3.4.3 Linhas de Execução Branca São De Alta Prioridade
Se você alguma vez tiver que decidir entre endireitar uma linha executiva branca linear ou endireitar linhas de dados de algum tipo, sempre endireite a linha executiva branca.
#### 3.4.4 Os Gráficos Devem Ser Comentadas Razoavelmente
Os blocos de nodes devem ser incluídos em comentários que descrevam seu comportamento de nível superior. Embora cada função deva ser bem nomeada para que cada node individual seja facilmente legível e compreensível, grupos de nodes que contribuem para um propósito devem ter seu propósito descrito em um bloco de comentário. Se uma função não tiver muitos blocos de nodes e ficar claro que os nodes estão servindo a um propósito direto no objetivo da função, eles não precisam ser comentados, pois o nome e a descrição da função devem ser suficientes.
#### 3.4.5 Os Gráficos Devem Lidar Com Error de Casting Onde Apropriado
Se uma função ou evento presumir que uma conversão sempre é bem-sucedida, ele deve relatar apropriadamente uma falha na lógica se o casting falhar. Isso permite que outras pessoas saibam por que algo que "deveria funcionar" não funciona. Uma função também deve tentar uma recuperação normal após um cast com falha se for conhecido que a referência que está sendo lançada pode falhar durante o cast.
Isso não significa que cada node de cast deve ter sua falha tratada. Em muitos casos, especialmente eventos relacionados a coisas como colisões, espera-se que o fluxo de execução termine silenciosamente em um cast com falha.
#### 3.4.6 Os Gráficos Não Devem Ter Nodes Pendentes / Soltos / Mortos
Todos os nodes em todos os gráficos do blueprint devem ter um propósito. Você não deve deixar nodes de blueprint pendurados por aí que não têm propósito ou não são executados.
**[⬆ Voltar ao topo](#table-of-contents)**
## 4. Static Meshes
Esta seção se concentrará em assets Static Mesh e seus internos.
### Seções
> 4.1 [UVs](#s-uvs)
> 4.2 [LODs](#s-lods)
> 4.3 [Encaixe Modular Sem Socket](#s-modular-snapping)
> 4.4 [Deve Ter Colisão](#s-collision)
> 4.5 [Escala Correta](#s-scaled)
### 4.1 UVs Static Mesh
Se o Linter está reportando maus UVs e você não consegue rastreá-los, abra o arquivo resultante `.log` no seu projeto `Saved/Logs` para obter detalhes exatos sobre o motivo da falha. Espero que incluam essas mensagens no relatório Lint no futuro.
#### 4.1.1 Todos Meshes Devem Ter UVs
Bem simples. Todos os meshes, independentemente de como devem ser usadas, não devem ter UVs faltando.
#### 4.1.2 Todos Meshes Não deve ter sobreposição UVs de Lightmaps
Bem simples. Todas os meshes, independentemente de como devem ser usadas, devem ter UVs válidos sem sobreposição.
### 4.2 LODs Devem Ser Configurados Corretamente
Esta é uma verificação subjetiva por projeto, mas como regra geral, qualquer meshe que pode ser vista em distâncias variáveis deve ter LODs adequados.
### 4.3 Assests Modulares Sem Soquete Devem Se Encaixar na Grade de Forma Limpa
Esta é uma verificação subjetiva por asset, no entanto, quaisquer assets modulares sem soquete devem se encaixar perfeitamente com base nas configurações de grade do projeto.
Fica a critério do projeto se encaixar com base em uma grade de 2 ou em uma grade de base 10. No entanto, se você estiver criando assets modulares sem soquete para o marketplace, o requisito da Epic é que eles se encaixem perfeitamente quando a grade for configurada para 10 unidades ou mais.
### 4.4 Todos Meshes Devem Ter Colisão
Independentemente de um assets ser usado para colisão em um level, todos os meshes devem ter a colisão adequada definida. Isso ajuda o mecanismo com coisas como cálculos de limites, oclusão e iluminação. A colisão também deve ser bem formada para o asset.
### 4.5 Todos Meshes Deve Ser Dimensionado Corretamente
Esta é uma verificação subjetiva por projeto; no entanto, todos os assets devem ser dimensionados corretamente para o projeto. Os level designers ou autores de blueprint não devem ter que ajustar a escala dos meshes para que sejam confirmadas no editor. Redimencionar meshes na engine deve se tratadas como uma substituição de escala, não uma correção de escala.
**[⬆ Voltar ao topo](#table-of-contents)**
## 5. Niagara
Esta seção se concentrará em assets Niagara e seus internos.
### Seções
> 5.1 [Regras de Nomenclatura](#ng-rules)
### 5.1 Sem Espaços, Nunca
Conforme mencionado em [00.1 Identificadores Proibidos](#00), espaços e todos os caracteres de espaço em branco são proibidos em identificadores. Isso é especialmente verdadeiro para os sistemas Niagara, pois torna o trabalho com as coisas significativamente mais difícil, senão impossível, ao trabalhar com HLSL ou outros meios de script dentro do Niagara e ao tentar fazer referência a um identificador.
(Contribuição original por [@dunenkoff](https://github.com/Allar/ue5-style-guide/issues/58))
**[⬆ Voltar ao topo](#table-of-contents)**
## 6. Levels / Maps
[Veja a Nota de Terminologia](#terms-level-map) sobre "levels" vs "maps".
Esta seção se concentrará em assets de Level e seus internos.
### Seções
> 6.1 [Sem Erros ou Avisos](#levels-no-errors-or-warnings)
> 6.2 [A Iluminação Deve Ser Construída](#levels-lighting-should-be-built)
> 6.3 [Nenhum "Z Fighting" Visível ao Jogador](#evels-no-visible-z-fighting)
> 6.4 [Regras Específicas de Marketplace](#evels-levels-mp-rules)
### 6.1 Sem Erros ou Avisos
Todos os levels devem carregar sem erros ou avisos. Se um level for carregado com erros ou avisos, eles devem ser corrigidos imediatamente para evitar problemas em cascata.
Você pode executar uma verificação de mapa em um level aberto no editor usando o comando de console "map check".
Observação: o Linter é ainda mais rígido nisso do que o editor atualmente, e detectará erros de carregamento que o editor resolverá sozinho.
### 6.2 A Iluminação Deve Ser Construída
É normal que, durante o desenvolvimento, os levels ocasionalmente não tenham iluminação. Ao fazer um teste/building interna/de envio ou qualquer building a ser distribuída, no entanto, a iluminação deve sempre ser construída.
### 6.3 No Player Visible Z Fighting
Nenhum level deve ter [z-fighting](https://en.wikipedia.org/wiki/Z-fighting) em todas as áreas visíveis ao jogador.
### 6.4 Regras Específicas de Marketplace
Se um projeto for vendido no Marketplace UE4, deve seguir essas regras.
### 6.4.1 Level de Overview
Se o seu projeto contém assets que devem ser visualizados ou demonstrados, você deve ter um mapa dentro do seu projeto que contém o nome "Overview".
Esse mapa overview, se estiver visualizando assets, deve ser configurado de acordo com [As Diretrizes da Epic](http://help.epicgames.com/customer/en/portal/articles/2592186-marketplace-submission-guidelines-preparing-your-assets#Required%20Levels%20and%20Maps).
Por exemplo, `InteractionComponent_Overview`.
### 6.4.2 Level Demo
Se o seu projeto contém assets que devem ser demonstrados ou vêm com algum tipo de tutorial, você deve ter um mapa dentro do projeto que contém o nome "Demo". Este nível também deve conter documentação de alguma forma que ilustre como usar seu projeto. Veja o projeto Exemplos de Conteúdo da Epic para bons exemplos de como fazer isso.
Se o seu projeto for uma mecânica de jogo ou outra forma de sistema em oposição a um pacote de arte, isso pode ser o mesmo que seu mapa "Overview".
Por exemplo, `InteractionComponent_Overview_Demo`, `ExplosionKit_Demo`.
**[⬆ Voltar ao topo](#table-of-contents)**
## 7. Texturas
Esta seção se concentrará em assets de textura e suas propriedades.
### Seções
> 7.1 [Dimensões são poderes de 2](#textures-dimension)
> 7.2 [A densidade da textura deve ser uniforme](#textures-dimension)
> 7.3 [As texturas não devem ser maiores que 8192](#textures-max-size)
> 7.4 [Grupos de textura corretos](#textures-textures-group)
### 7.1 Dimensões são poderes de 2
Todas as texturas, exceto as texturas de IU, devem ter suas dimensões em múltiplos de potências de 2. As texturas não precisam ser quadradas.
Por exemplo, `128x512`,` 1024x1024`, `2048x1024`,` 1024x2048`, `1x512`.
### 7.2 A densidade da textura deve ser uniforme
Todas as texturas devem ter um tamanho apropriado para seu caso de uso padrão. A densidade de textura apropriada varia de projeto para projeto, mas todas as texturas dentro desse projeto devem ter uma densidade consistente.
Por exemplo, se a densidade da textura de um projeto é de 8 pixels por 1 unidade, uma textura que deve ser aplicada a um cubo de 100x100 unidades deve ser 1024x1024, pois é a potência mais próxima de 2 que corresponde à densidade da textura do projeto.
### 7.3 As texturas não devem ser maiores que 8192
Nenhuma textura deve ter uma dimensão que exceda 8192 em tamanho, a menos que você tenha um motivo muito explícito para fazer isso. Freqüentemente, usar uma textura tão grande é simplesmente um desperdício de recursos.
### 7.4 As texturas devem ser agrupadas corretamente
Cada textura possui uma propriedade "Texture Group" usada para LOADing, e isso deve ser definido corretamente com base em seu uso. Por exemplo, todas as texturas da IU devem pertencer ao grupo de textura da IU.
**[⬆ Voltar ao topo](#table-of-contents)**
## Principais Contribuintes
* [Michael Allar](http://allarsblog.com): [GitHub](https://github.com/Allar), [Twitter](https://twitter.com/michaelallar)
* [CosmoMyzrailGorynych](https://github.com/CosmoMyzrailGorynych)
* [billymcguffin](https://github.com/billymcguffin)
* [akenatsu](https://github.com/akenatsu)
## Licença
Copyright (c) 2016 Gamemakin LLC
Veja [LICENSE](/LICENSE)
**[⬆ Voltar ao topo](#table-of-contents)**
## Emendas
Recomendamos que você crie um fork deste guia e altere as regras para se adequar ao Guia de Estilo de sua equipe. Abaixo, você pode listar algumas alterações ao Guia de Estilo. Isso permite que você atualize periodicamente seu guia de estilo sem ter que lidar com conflitos de mesclagem.
# };
================================================
FILE: docs/gettingstarted.md
================================================
# Getting Started
## Requirements
* You will need a launcher version of Unreal Engine 4 version 4.24 or later.
* You must purchase (for free) the Linter plugin on the Unreal Engine Marketplace.
@TODO: Add link here once I have it
## Installing From The Launcher
1. Close all your instances of Unreal Engine 4
2. Using the Epic Launcher find Linter in your Vault
3. Use the Install to Engine button to install Linter to your Engine
## Enabling Linter
1. Open your project
2. Open the Plugins window by clicking Edit on the main toolbar and navigating to Plugins
3. Search for Linter
4. Enable the Linter plugin by ensuring the Enabled checkbox is checked
5. Restart the editor
## Using Linter
Once installed there isn't much in the way of using Linter. Operating Linter is pretty straightforward:
1. Right-click on a content folder in your project
2. Click "Scan with Linter"
3. Select the ruleset you would like to use for linting
4. Wait for the results
## The Lint Report
Once a project is scanned, you will be presented with a Lint Report that provides an overall summary of the state of your project.
================================================
FILE: docs/howitworks.md
================================================
# How Does Linting Work?
Linter's bundled rulesets are included in the Linter Plugin content folder. Engine and Project plugin folders might be hidden in your engine. To show them, make sure the checkboxes next to Show Engine Content and Show Plugin Content are both checked in your Content Browser's View Options.
## Dissecting a Linter Rule Set
Linters are defined by `LintRuleSets`, essentially a fancy [Data Asset](https://www.youtube.com/watch?v=gLWXZ3FXhO8). In the above example, we are looking at the `MarketplaceLintRuleSet` asset which defines all of the rules we want to use when scanning for marketplace guideline compliance.
In the above image you'll see that this `LintRuleSet` uses a `NamingConvention` Data Asset named `MarketplaceNamingConvention` In addition to a NamingConvention asset, `LintRuleSet` assets also contain something called a Class Lint Rules Map. This is a map of Unreal Engine 4 classes paired with a list of `LintRules`, which are assets that make up individual rules that we'll cover later.
When objects in an Unreal Engine 4 project are linted, they are scanned using the rules that match the "most specific" class defined in the Class Lint Rules Map. You can use any class in this map, with the base `UObject` being a special case.
Unfortunately at this time the Unreal Engine 4 editor does not allow `UObject` as a valid value as a key in this Class Lint Rules Map, so if you want to define rules that you want to scan `UObjects` with, please use the `AnyObject_LinterDummyClass` class instead.
With the above example ruleset, when the Linter comes across a `UBlueprint` asset it will scan that asset using the four lint rules defined above. This is because `UBlueprint` is a more specific class definition than `UObject`. Another asset type, such as a data asset, will instead use the `AnyObject_LinterDummyClass` rules when being scanned unless there is a more specific matching class defined in the ruleset than `UObject`.
**NOTE:** Currently there isn't support for allowing cascading rule checks, i.e. allowing a `UBlueprint` being scanned against rules paired with `UBlueprint` *as well as* `UObject`. This support is planned to be added in a future release. See [todo](/todo).
## How Lint Rules Are Implemented
While `LintRules` can be implemented in both Blueprint and C++, currently there aren't too many functions exposed to Blueprint that deal with asset metadata and lower level asset management checks and tasks. It is currently strongly recommended that you do your rule checking logic in C++ and then only expose configuration settings to a Blueprint class.
All of Linter's bundled `LintRules` are Blueprint child classes that parent from a native C++ `LintRule`, with the goal that the Blueprint `LintRules` only expose configuration options.
### PassesRule_Internal_Implementation
The core of implementing your own `LintRule` is to implement the `PassesRule_Internal_Implementation` function. This function can be implemented in either C++ or Blueprint as this is a `BlueprintNativeEvent`.
This should be where the business logic of your `LintRule` operates. To report a rule violation, push a new `FLintRuleViolation` to the `OutRuleViolations` array and return false. You should always return false if **any** rule is violated and you should always return true if **no** rules were violated. A `FLintRuleViolation` is simply a struct that has a reference to the asset that is violating the rule, a reference to the rule that is being violated, and potentially any additional optional recommended text to display to the user reading the Lint Report.
Implementing this function is all you need for your `LintRule` to be functional and ready for use. For the sake of example, here is how the Unreal Engine Marketplace Guideline rule for ensuring your textures are not too big is implemented:
```cpp
bool ULintRule_Texture_Size_NotTooBig::PassesRule_Internal_Implementation(UObject* ObjectToLint, const ULintRuleSet* ParentRuleSet, TArray& OutRuleViolations) const
{
const UTexture2D* Texture = CastChecked(ObjectToLint);
int32 TexSizeX = Texture->GetSizeX();
int32 TexSizeY = Texture->GetSizeY();
// Check to see if textures are too big
if (TexSizeX > MaxTextureSizeX || TexSizeY > MaxTextureSizeY)
{
FText RecommendedAction = NSLOCTEXT("Linter", "LintRule_Texture_Size_NotTooBig_TooBig", "Please shrink your textures dimensions so that they fit within {0}x{1} pixels.");
OutRuleViolations.Push(FLintRuleViolation(ObjectToLint, GetClass(), FText::FormatOrdered(RecommendedAction, MaxTextureSizeX, MaxTextureSizeY)));
return false;
}
return true;
}
```
In the above code, we simply check to see if the `ObjectToLint` is a texture with width or height exceeding a `MaxTextureSizeX/MaxTextureSizeY`, which is defined in our Blueprint child as `8192`. This allows us to easily scan for textures that are bigger than 8k. If we ever want to decrease or increase the size of our textures allowed under this rule, we can easily do so by editing the `MaxTextureSizeX/MaxTextureSizeY` in Blueprint without requiring any code changes or code compiling.
It is recommended that you create a Blueprint child of your native classes to fill out the Rule's display info. This way the rule can also have verbiage updates without requiring code edits.
### PassesRule Is Most Likely Not What You Want
`LintRules` also have a virtual function called `PassesRule`. This is not meant for containing the business logic of your `LintRule`. This is a public `BlueprintCallable` function that allows your `LintRule` to have a Blueprint implementation of `PassesRule_Internal_Implementation`.
You should only implement this if you want to "early out" of the linting process. Linter's strategy is to try to implement error handling in `PassesRule` for things like possible null checks or invalid objects and then only performing the actual scan logic inside `PassesRule_Internal_Implementation`. You **do not** need to implement your own `PassesRule`.
### IsRuleSuppressed is optional
`LintRules` can also be programmatically suppressed by implementing the `IsRuleSuppressed` function. This function is called automatically by the base `PassesRule` implementation. If you want to simply suppress a rule, do so here instead of `PassesRule`.
## How Lint Naming Conventions Are Implemented
`NamingConvention` assets are simply a list of naming conventions as a data asset. `LintRules` will have access to the `NamingConvention` data asset that is defined in the lint rule's parent `LintRuleSet`. The `NamingConvention` data asset isn't responsible for any implementation logic. Instead `LintRules` are written to perform these naming convention checks using the given `NamingConvention` data asset as configuration.
## LintRuleCollections... collect rules
Sometimes it is easier to treat a collection of rules as a single rule. In this case, you can create a `LintRuleCollection` class that simply defines a list of other `LintRules`. This is very useful when dealing with repetitive path and file name lint rules.
## Video Walkthrough of Creating A LintRuleSet
@TODO: Get this edited, uploaded, submitted, embedded
## Automated Linting via Commandlets
The Linter plugin adds a Commandlet that you can run against your project via commandline. It will return an error code of 1 if the linting process fails for any reason. It will return an error code of 2 if Linter reports any errors, or warnings as well if `-TreatWarningsAsErrors` is passed on the commandline.
To invoke the commandlet, run your Editor binary (i.e. `D:\UE424\Engine\Binaries\Win64\UE4Editor-Cmd.exe`), followed by the path to your `.uproject` (i.e. `"C:\Users\Allar\Documents\Unreal Projects\Linterv2Test\Linterv2Test.uproject"`), followed by the arg `-run=Linter`.
Full command for example, `D:\UE424\Engine\Binaries\Win64\UE4Editor-Cmd.exe "C:\Users\Allar\Documents\Unreal Projects\Linterv2Test\Linterv2Test.uproject" -run=Linter`.
This will run Linter against the `/Game` path, a.k.a. your project's path, and return error code 0 if there are no errors.
### Specifying which Lint Rule Set to use
All Lint Rule Sets now have a filed named `Commandlet Name` which represents a simple name to identify them via commandline.
The Gamemakin LLC UE4 Style Guide's `Commandlet Name` is `ue4.style`, where the Unreal Engine Marketplace Guidelines uses the name `marketplace`.
To specify this, use the `-RuleSet=` arg. For example, `-RuleSet=ue4.style` will use the Gamemakin lint rule set. `-RuleSet=marketplace` will use the UnrealEngine Marketplace Guidelines. If `-RuleSet=` is not provided, Linter will use the project's default Lint Rule Set.
### Additional Args
#### Content Paths
You can tell Linter to scan a list of folders to scan. They should generally be in the UE4 path form of `/Game/Content/...`. If a path includes spaces, wrap it in quotes.
For example, if you only wanted to scan folders `Apple` and `Orange Stuff` inside your project's `Content` folder...
`D:\UE424\Engine\Binaries\Win64\UE4Editor-Cmd.exe "C:\Users\Allar\Documents\Unreal Projects\Linterv2Test\Linterv2Test.uproject" /Game/Content/Apple "/Game/Content/Orange Stuff" -run=Linter`.
This will scan both the `Apple` and `Orange Stuff` folders inside your project's `Content` folder. You can also pass in `Engine` and plugin folders. If no path is provided, the default will always be `/Game`.
#### JSON Report
To generate a `.json` report, you can add the switch `-json` to generate a `.json` report in your project's `Saved/LintReports/` folder. You can override the name of the report via `-json=ReportName.json`. If you specify a relative path it will be relative to the `Saved/LintReports/` folder. You can also provide an absolute path to write the `.json` report to.
#### HTML Report
To generate a `.html` report, you can add the switch `-html` to generate a `.html` report in your project's `Saved/LintReports/` folder. You can override the name of the report via `-html=ReportName.html`. If you specify a relative path it will be relative to the `Saved/LintReports/` folder. You can also provide an absolute path to write the `.html` report to.
#### TreatWarningsAsErrors
If you use the `-TreatWarningsAsErrors` switch, Linter will return an error code of 2 if the report contains any warnings. By default, Linter only returns an error code if it fails to lint or if the lint report contains errors.
================================================
FILE: docs/index.md
================================================
# Welcome to Linter and Gamemakin LLC Style Guide Documentation
This is the official documentation for Linter and the [Gamemakin LLC Style Guide](http://ue4.style). If you are looking for help or support, please try the [Gamemakin LLC Community Discord](http://discord.gamemak.in).
## About Linter
Linter is an Unreal Engine 4 plugin available on the Unreal Engine Marketplace that can be used for automated scanning and reporting of a UE4 project's adherence to style guide standards. It can scan through all of your project's content using programmatic rulesets and tell you when you aren't following a rule. This is a fairly common type of tool usually seen in web development, but now we can do it with Unreal Engine!
By default Linter is bundled with two rule sets:
1. The [Unreal Engine Marketplace Guidelines](https://www.unrealengine.com/marketplace-guidelines)
1. The [Gamemakin LLC Style Guide](http://ue4.style)
## About the Gamemakin LLC Style Guide
While Linter is now capable of supporting multiple rule sets, Linter was originally developed with the Gamemakin LLC Style Guide in mind. This style guide is an opinionated set of guidelines written by [Michael Allar](http://www.twitter.com/michaelallar) for Unreal Engine 4 projects that continue to grow, change, and respond to newer and better organization patterns as well as community feedback.
This style guide is not meant to be the definitive solution to all projects, but it is open-sourced in the hopes that those without style guides can use it as a starting point for their practices and try to come to a common consensus to many aspects of working with Unreal Engine 4.
It can be found at the following URL: [http://ue4.style](http://ue4.style)
## About the Unreal Engine Marketplace Guidelines
If you are creating content for the Unreal Engine Marketplace, your content must adhere to Epic's guidelines [which can be found on their site](https://www.unrealengine.com/marketplace-guidelines).
Linter, Gamemakin LLC, and Michael Allar do not have any control or influence over these guidelines as well as whether your assets meet the required standards for the Unreal Engine Marketplace, but Linter is designed to help you conform to their rules by scanning your project against the rules they will be validated with.
================================================
FILE: docs/style.md
================================================
# Gamemakin LLC Style Guide
For information about how Linter scans against the Gamemakin LLC Style Guide, please see the style guide itself at [http://ue4.style](http://ue4.style) as the style guide is marked up with its own Linter annotations.
================================================
FILE: docs/todo.md
================================================
# The Future of Linter and the Gamemakin LLC Style Guide
This page documents active efforts with Linter and the Gamemakin LLC Style Guide that may be in progress or otherwise incomplete.
## Planned Future Features
1. Finish video tutorial on the creation of a new lint ruleset
1. Allowing rule scanning to support multiple class matches in a class lint rules map
## Future Considerations
* Figure out a way to facilitate community lint rule sets
================================================
FILE: docs/unrealguidelines.md
================================================
# Unreal Engine Marketplace Guidelines
This page covers how Linter implements rule sets based off of the [Unreal Engine Marketplace Guidelines](https://www.unrealengine.com/marketplace-guidelines). Not every guideline is currently supported but it is the goal of Linter to continually improve support for the Unreal Engine Marketplace Guidelines as well as other commonly used style guides.
If you would like to contribute by adding support for additional guidelines, please join the discussion in the [Gamemakin LLC Community Discord](http://discord.gamemak.in).
## Disclaimer
You are not guaranteed to have your product submission accepted by the Unreal Engine Marketplace simply because you might pass all these rules, however failing these rules will make your submission incredibly more likely to be rejected.
## 2.3.6 Particle Effects
### 2.3.6.b [Particle emitter names must be accurate and relevant and must not be "Particle Emitter" unless they're the only emitter in a given particle system](https://www.unrealengine.com/en-US/marketplace-guidelines#236b)
Linter's interpretation of this is to simply check to see if a `UParticleSystem` asset has 2 or more emitters, and if it does, check to see if any of the emitters are named "Particle Emitter". If they are, then this rule is being violated.
This is handled by `Blueprint'/Linter/MarketplaceLinter/LintRules/MPLR_Particles_EmitterNames.MPLR_Particles_EmitterNames'`.
## 2.3.7 Textures
### 2.3.7.a [Both dimensions of each texture should have a size that is a power of 2 where applicable (e.g. 1024x512 or 1024x4096)](https://www.unrealengine.com/en-US/marketplace-guidelines#237a)
Linter's interpretation is to do a simple "power of two" math test on both the width and the height of all textures. If a texture fails this power of two math test, it then is checked to see if it's `LODGROUP` is exempt from this rule. For the Unreal Engine Marketplace Guidelines, this rule set is configured to only allow textures of the `UI` `LODGROUP` to not have power of two sizes.
This is handled by `Blueprint'/Linter/MarketplaceLinter/LintRules/MPLR_Texture2D_PowerOfTwo.MPLR_Texture2D_PowerOfTwo'`.
### 2.3.7.b [Textures must have a maximum size in either dimension of 8192](https://www.unrealengine.com/en-US/marketplace-guidelines#237b)
Linter's interpretation of this is to make sure a texture's width or height isn't bigger than 8192. That simple.
This is handled by `Blueprint'/Linter/MarketplaceLinter/LintRules/MPLR_Texture2D_Size_NotTooBig.MPLR_Texture2D_Size_NotTooBig'`.
## 2.4 Audio
### 2.4.c [Audio files must have a sample rate of 22050 Hz or 44100 Hz with no audio defects](https://www.unrealengine.com/en-US/marketplace-guidelines#24c)
Linter's interpretation of this is pretty straight forward. `USoundWave` assets must have sample rates of either 22050 or 44100.
This is handled by `Blueprint'/Linter/MarketplaceLinter/LintRules/MPLR_SoundWave_SampleRate.MPLR_SoundWave_SampleRate'`.
## 2.5 Blueprints
### 2.5.d [Blueprints must have no loose nodes unless they’re commented for example/tutorial purposes](https://www.unrealengine.com/en-US/marketplace-guidelines#25d)
Linter's interpretation of this is that a `UBlueprint` that has any node on any of its graphs that has zero connections to any other node.
This is handled by `Blueprint'/Linter/MarketplaceLinter/LintRules/MPLR_Blueprint_LooseNodes.MPLR_Blueprint_LooseNodes'`.
### 2.5.e [Blueprints must generate no errors or consequential warnings](https://www.unrealengine.com/en-US/marketplace-guidelines#25e)
Linter's interpretation of this is that a `UBlueprint` must not have a compile status of `BS_Error` or `BS_UpToDateWithWarnings`.
That is, the compile button for this Blueprint should not have any error or warning icon on it.
This is handled by `Blueprint'/Linter/MarketplaceLinter/LintRules/MPLR_Blueprint_Compiles.MPLR_Blueprint_Compiles'`.
## 2.7 File Structure
### 2.7.1.a [Folder and files must be accurate and consistent in naming convention within the context of their project](https://www.unrealengine.com/en-US/marketplace-guidelines#271a)
Linter's interpretation of this is that all assets should match a pattern defined in the rule set's `NamingConvention` asset.
The Marketplace `NamingConvention` asset is `MarketplaceNamingConvention'/Linter/MarketplaceLinter/MarketplaceNamingConvention.MarketplaceNamingConvention'` and the rule that checks for this is `Blueprint'/Linter/MarketplaceLinter/LintRules/MPLR_IsNamedCorrectly.MPLR_IsNamedCorrectly'`.
### 2.7.1.b [Folders and files must not be vaguely-named such as \"Assets\", \"NewFolder\", etc.](https://www.unrealengine.com/en-US/marketplace-guidelines#271b)
Linter's interpretation of this is that all path elements must never be "Assets" or "NewFolder".
This is handled by `Blueprint'/Linter/MarketplaceLinter/LintRules/MPLR_Path_DisallowedPathNames.MPLR_Path_DisallowedPathNames'`.
### 2.7.1.c [Folder and file names must contain only English alphanumeric characters and underscores](https://www.unrealengine.com/en-US/marketplace-guidelines#271c)
Linter's interpretation of this is that all path elements are tested against a Regular Expression `[^a-zA-Z0-9_]` which is only valid if the entire path element does not have any character except the letters "a through z", "A through Z", "0 through 9", and the '_' character.
This is handled by `Blueprint'/Linter/MarketplaceLinter/LintRules/MPLR_Path_AlphaNumeric.MPLR_Path_AlphaNumeric'`.
### 2.7.2.b [In order to reduce migration conflicts after importing project files from the Epic Games Launcher, all project-specific assets must be stored in one top level folder; there must be no other folders or files directly under the Content folder](https://www.unrealengine.com/en-US/marketplace-guidelines#272b)
Linter's interpretation of this is that the parent folder of any asset should not be the path `/Content/`.
This is handled by `Blueprint'/Linter/MarketplaceLinter/LintRules/MPLR_Path_NoTopLevelAssets.MPLR_Path_NoTopLevelAssets'`.
### 2.7.2.d [Including the name of the top level folder under the Content folder, all asset file paths must be 140 characters or less](https://www.unrealengine.com/en-US/marketplace-guidelines#272d)
Linter's interpretation of this is that the path of any asset returned by `UObject::GetPathName()`, with the redundant asset name chopped off, should not be longer than 140 characters.
This is handled by `Blueprint'/Linter/MarketplaceLinter/LintRules/MPLR_Path_IsNotTooLong.MPLR_Path_IsNotTooLong'`. The path name that is used for this asset for example would be `/Linter/MarketplaceLinter/LintRules/MPLR_Path_IsNotTooLong'`.
================================================
FILE: marketplace-compatibility.md
================================================
# UE4 Marketplace TRC + Style Guide and Linter Compatibility
Epic's Marketplace TRC can be found here: https://forums.unrealengine.com/showthread.php?151905-Marketplace-Technical-Review-Checklist
This document shows its compatibility with the style guide on this repo, as well as the UE4 Marketplace Plugin Linter.
## Icon Guide:
* :white_check_mark: - Compatible
* :green_heart: - Linter Supported (Can currently be checked through automation)
* :x: - Not Compatible
* :o: - See note
## General
| Line | Review Check Item | Compatibility Notes |
| :---: | :------------------------------------------------------------------------- | :------------------------------------------------------------------------------ |
| 4 | Submission is in Unreal Engine 4 | :white_check_mark::green_heart: If you can run Linter, you pass. |
| 5 | Project contains correct files and folders | :white_check_mark: If you can run Linter, and distribute correctly, you pass. |
| 6 | Submission contains enough primary assets | :o: You should generally always pass this. Could automate if this were more specific. |
| 7 | Folder hierarchy is structured correctly | :x: This style guide actively fights against the folder structure desired. [See #2](http://ue4.style#2) |
| 8 | First tier folders are named for asset type | :x: This style guide actively fights against the folder structure desired. [See #2](http://ue4.style#2) |
| 9 | All files in perspective folders | :white_check_mark::green_heart: Although structure is incompatible, files are checked for structure. [See #2](http://ue4.style#2) |
| 10 | Project is free of unused folders and assets | :white_check_mark::o: [See #2.2](http://ue4.style#2.2), [See #2.3](http://ue4.style#2.9), [See #2.9](http://ue4.style#2.9), and remove unused Epic starter / example content |
| 11 | Naming conventions present, consistent, and acceptable | :white_check_mark::green_heart: [See #1](http://ue4.style#1) |
| 12 | Assets names are in English and Alpha-Numeric | :white_check_mark::green_heart: [See #2.1.3](http://ue4.style#2.1.3) |
| 13 | Assets names identify asset types | :white_check_mark::green_heart: [See #1](http://ue4.style#1) |
| 14 | Assets names are consistent | :white_check_mark::green_heart: [See #1](http://ue4.style#1) |
## Maps
| Line | Review Check Item | Compatibility Notes |
| :---: | :------------------------------------------------------------------------- | :------------------------------------------------------------------------------ |
| 16 | Pack contains Maps | :white_check_mark::green_heart: Linter will check for map issues if maps exist. |
| 17 | Pack contains Overview Map | :white_check_mark: [See #6.4.1](http://ue4.style#6.4.1) |
| 18 | Overview Map is set up appropriately and named correctly | :white_check_mark: [See #6.4.1](http://ue4.style#6.4.1) |
| 19 | Lighting has been built on all maps | :white_check_mark: [See #6.2](http://ue4.style#6.2) |
| 20 | All maps are free of errors and/or warnings | :white_check_mark::green_heart: [See #6.1](http://ue4.style#6.1) |
| 21 | No Z fighting or overlapping polygons in maps | :white_check_mark: [See #6.3](http://ue4.style#6.3) |
| 22 | Pack contains Demo Map | :white_check_mark: [See #6.4.2](http://ue4.style#6.4.2) |
| 23 | Demo Map is set up appropriately and named correctly | :white_check_mark: [See #6.4.2](http://ue4.style#6.4.2) |
| 24 | Displays functionality effectively | :white_check_mark: [See #6.4.2](http://ue4.style#6.4.2) |
| 25 | In editor tutorial/documentation included | :white_check_mark: [See #6.4.2](http://ue4.style#6.4.2) |
## Quality
| Line | Review Check Item | Compatibility Notes |
| :---: | :------------------------------------------------------------------------- | :------------------------------------------------------------------------------ |
| 27 | Assets are free of visibly obvious discrepancies | :o: Currently a subjective check. |
| 28 | Assets function without detriment to performance | :o: Currently a subjective check. |
| 29 | All assets are complete and function as intended | :o: Currently a subjective check. |
| 30 | Assets are not easily reproduced | :o: Currently a subjective check. |
| 31 | Pack contains overall good design and concepts | :o: Currently a subjective check. |
## Legal
Gamemakin LLC and its product Linter makes no effort to check for legal compliance for your project on your behalf. We are not lawyers and do not have that capability and can not offer legal advice. That said, we vehemently recommend [not breaking the law](http://ue4.style#0.5).
| Line | Review Check Item | Compatibility Notes |
| :---: | :------------------------------------------------------------------------- | :------------------------------------------------------------------------------ |
| 33 | Seller owns rights to distribute content | :white_check_mark: See section note. [See #0.5](http://ue4.style#0.5) |
| 34 | Does not contain copyrighted or trademarked content | :white_check_mark: See section note. [See #0.5](http://ue4.style#0.5) |
| 35 | Pack is free of stolen/pirated content | :white_check_mark: See section note. [See #0.5](http://ue4.style#0.5) |
| 36 | Epic/Unreal content is used for display/example only | :white_check_mark: See section note. [See #0.5](http://ue4.style#0.5) |
| 37 | Public Domain Content meets guideline requirements | :white_check_mark: See section note. [See #0.5](http://ue4.style#0.5) |
| 38 | Project is self-sustained | :white_check_mark: See section note. [See #0.5](http://ue4.style#0.5) |
| 39 | Additional requirements are available on the Marketplace | :white_check_mark: See section note. [See #0.5](http://ue4.style#0.5) |
| 40 | Pack does not contain assets that could be considered offensive | :white_check_mark: See section note. [See #0.5](http://ue4.style#0.5) |
## Textures
| Line | Review Check Item | Compatibility Notes |
| :---: | :------------------------------------------------------------------------- | :------------------------------------------------------------------------------ |
| 42 | Pack contains Textures | :white_check_mark::green_heart: |
| 43 | Textures are set to Power of 2 | :white_check_mark: [See #7.1](http://ue4.style#7.1) |
| 44 | All textures are appropriate resolutions for their respective assets | :white_check_mark: [See #7.2](http://ue4.style#7.2) |
| 45 | Maximum texture size is 8192 for general use and/or 2048 for mobile textures in either dimension | :white_check_mark: [See #7.3](http://ue4.style#7.3) |
| 46 | All textures use the correct texture group based on purpose | :white_check_mark: [See #7.4](http://ue4.style#7.4) |
## Materials
| Line | Review Check Item | Compatibility Notes |
| :---: | :------------------------------------------------------------------------- | :------------------------------------------------------------------------------ |
| 48 | Pack contains Materials | :white_check_mark::green_heart: |
| 49 | All Materials are set up correctly and are optimized for intended purpose | :o: Currently a subjective check. |
| 50 | Material instances used where appropriate | :o: Currently a subjective check. |
| 51 | Mobile material assets use only BaseColor, Roughness, and Normal from textures | :o: Style guide has no mobile-specific distinctions. |
| 52 | Specular is not specified unless used | :o: If "Yes" then "Yes", otherwise "No"? Too vague to understand. |
## Meshes
| Line | Review Check Item | Compatibility Notes |
| :---: | :------------------------------------------------------------------------- | :------------------------------------------------------------------------------ |
| 54 | Pack contains Meshes | :white_check_mark::green_heart: |
| 55 | LOD's are set up correctly | :white_check_mark: [See #4.2](http://ue4.style#4.2) |
| 56 | Assets are modular | :o: 'Recommended Check'. It does not make sense to make this a hard rule, as hero assets are generally not modular. |
| 57 | Modular pieces are adaptable for repurposing | :white_check_mark: This is the definition of modular. |
| 58 | Assets snap cleanly on 10 cm grid | :white_check_mark: [See #4.3](http://ue4.style#4.3) |
| 59 | Has collision | :white_check_mark: [See #4.4](http://ue4.style#4.4) |
| 60 | Collision set up correctly | :white_check_mark: [See #4.4](http://ue4.style#4.4) |
| 61 | PhysicsAssets correctly set up | :o::white_check_mark: Style Guide currently does not have rules for Skeletal Meshes. This will be enforced however. |
| 62 | If less than 5 assets, all assets are rigged and animated | :o: Marketplace specific rule purely about quantity, guide does not apply. |
| 63 | No overlapping Lightmap UVs | :white_check_mark::green_heart: [See #4.4](http://ue4.style#4.4) |
| 64 | Assets scaled correctly | :white_check_mark: [See #4.5](http://ue4.style#4.5) |
## Blueprints
| Line | Review Check Item | Compatibility Notes |
| :---: | :------------------------------------------------------------------------- | :------------------------------------------------------------------------------ |
| 66 | Pack contains Blueprints | :white_check_mark::green_heart: |
| 67 | Blueprints use comments appropriately | :white_check_mark: [See #3.4.4](http://ue4.style#3.4.4) |
| 68 | Blueprints are clean and easy to read | :white_check_mark: [See #3.4](http://ue4.style#3.4) and its subsections. |
| 69 | Casts contain both a pass and fail condition | :o: Sometimes a graceful no-logic fail is acceptable. [See #3.4.5](http://ue4.style#3.4.5) |
| 70 | Custom Blueprint nodes contain "Static" prefix | :x: If this refers to a node's name, this makes zero sense, and Epic doesn't follow this in any form. If this refers to the fact that a function might be static, this also makes no sense and this rule should be re-written. After several months I have not been able to get clarification from the marketplace team as to what is intended here. |
| 71 | Custom Blueprint nodes from plugins categorized with plugin name as preface | :o: Style guide only applies this to static functions in a plugin. [See #3.3.5](http://ue4.style#3.3.5) |
| 72 | Functions, variables, and events use names that reflect intended purposes | :white_check_mark: [See #3.3.1](http://ue4.style#3.3.1) |
| 73 | No loose Blueprint nodes | :white_check_mark: [See #3.4.6](http://ue4.style#3.4.6) |
| 74 | Blueprint is free of errors and/or warnings | :white_check_mark::green_heart: [See #3.1](http://ue4.style#3.1) |
## Audio
| Line | Review Check Item | Compatibility Notes |
| :---: | :------------------------------------------------------------------------- | :------------------------------------------------------------------------------ |
| 76 | Pack contains Audio | :white_check_mark::green_heart: |
| 77 | All wav files have sound cues attached | :o: This reads like a 1:1 relationship between SoundWaves and SoundCues, when its very common to have one SoundCue reference many SoundWaves. Not sure of Marketplace Team's intention. |
| 78 | Audio is clean and not bitcrunched | :o: Currently a subjective check. |
| 79 | Audio sample rate is appropriate (44100 Hz or 22050 Hz for Game Assets) | :o: Style guide currently does not have rules for audio format. |
| 80 | Sound cues and wavs in separate "Cue" and "Wave" folders | :x: This style guide actively fights against the folder structure desired. [See #2](http://ue4.style#2) |
## Characters
Gamemakin LLC's Style Guide does not have character specfics as characters are quite diverse. Epic forces characters to adhere to the Epic Skeleton for marketplace assets even when a character should have a different skeleton due to things like having facial animations, having articulation and movements not supported by Epic's skeleton, having wildly different proportions to the point where using even re-targeted Epic animations don't make sense, and other factors.
When a humanoid does warrant being rigged to the Epic skeleton, we agree with every review item in this list. This checklist however is not fully compatible because we don't believe line item 83 should be enforced as strictly as it currently is.
| Line | Review Check Item | Compatibility Notes |
| :---: | :------------------------------------------------------------------------- | :------------------------------------------------------------------------------ |
| 82 | Pack contains Characters | :white_check_mark::green_heart: |
| 83 | Humanoid assets rigged to Epic skeleton | :o: See section note above. |
| 84 | Bones are not renamed | :o::white_check_mark: If using Epic skeleton, agree completely. See Section note. |
| 85 | Character is not weighted to any IK joints | :o::white_check_mark: If using Epic skeleton, agree completely. See Section note. |
| 86 | Epic Skeleton IK Joints are in skeleton hierarchy | :o::white_check_mark: If using Epic skeleton, agree completely. See Section note. |
| 87 | Joint orientations remain intact | :o::white_check_mark: If using Epic skeleton, agree completely. See Section note. |
| 88 | Skeleton is not scaled | :o::white_check_mark: If using Epic skeleton, agree completely. See Section note. |
## Animation
| Line | Review Check Item | Compatibility Notes |
| :---: | :------------------------------------------------------------------------- | :------------------------------------------------------------------------------ |
| 90 | Pack contains Animations | :white_check_mark::green_heart: |
| 91 | All animations imported from individual .FBX files | :x: Does not make sense. What about animations baked from physical simulations within UE4? What about single frame poses extracted from animations used for reference and additive posing within UE4? What about .FBX's with multiple takes in standard mo-cap pipelines using Motion Builder? |
| 92 | Animations are clean, consistent, and function as intended | :white_check_mark: All assets, regardless of type, should not be broken. |
## Weapons
| Line | Review Check Item | Compatibility Notes |
| :---: | :------------------------------------------------------------------------- | :------------------------------------------------------------------------------ |
| 94 | Pack contains Weapons | :white_check_mark::green_heart: |
| 95 | Weapons are scaled to epic skeleton and appear relatively scaled as intended when imported into a new project | :white_check_mark: [See #4.5](http://ue4.style#4.5) |
| 96 | Weapons with moving parts are rigged and animated | :white_check_mark: Definition of a weapon with moving parts. Otherwise it wouldn't have moving parts. |
## Particle Effects
| Line | Review Check Item | Compatibility Notes |
| :---: | :------------------------------------------------------------------------- | :------------------------------------------------------------------------------ |
| 98 | Pack contains Particle Effects | :white_check_mark::green_heart: |
| 99 | Emitter names are accurate and relevant to their displayed effects |:white_check_mark::green_heart: [See #5.1](http://ue4.style#5.1) |
| 100 | Particle systems meant to be viewed at multiple distances have correct LODs | :o: Currently a subjective check. |
| 101 | Effects optimized for their intended use | :o: Currently a subjective check. |
## Plugins
| Line | Review Check Item | Compatibility Notes |
| :---: | :------------------------------------------------------------------------- | :------------------------------------------------------------------------------ |
| 103 | Pack utilizes Plugins | :white_check_mark: |
| 104 | Required plugins in project are available on UE Marketplace | :o: Marketplace specific rule, style guide does not apply. |
| 105 | Unnecessary/Unused plugins are disabled | :o: Blueprint only projects can sometimes be forced to need C++ compiling when disabling unused built-in plugins. Until this is fixed, can not recommend fully disabling every unused plugin. |
## Notes From Reviewer
| Line | Review Check Item | Compatibility Notes |
| :---: | :------------------------------------------------------------------------- | :------------------------------------------------------------------------------ |
| 107 | Changes have previously been requested | :o: Specific to Marketplace Review Process, style guide does not apply. |
| 108 | Requested Changes Have Been Implemented | :o: Specific to Marketplace Review Process, style guide does not apply. |
================================================
FILE: mkdocs.yml
================================================
site_name: Linter and Style Guide Documentation
nav:
- Home: index.md
- Getting Started: gettingstarted.md
- How Does Linting Work?: howitworks.md
- Unreal Engine Marketplace Guidelines: unrealguidelines.md
- Gamemakin LLC Style Guide: style.md
- TODO: todo.md
theme: readthedocs
================================================
FILE: readthedocs.yml
================================================
# .readthedocs.yml
# Required
version: 2
mkdocs:
configuration: mkdocs.yml