ccclass update & compress-texture add (cocos-creator#138)

Author: LinYunMo

en/_layouts/website/header.html

@@ -2,7 +2,7 @@
 {% block book_header %}
 <div class="cocos-navbar navbar-collapse" id="navbar" role="navigation">
     <ul class="nav navbar-nav">
-        <li><a href="https://cocos.com" class="btn" target="_blank"><img src="https://forum.cocos.com/images/logo.png" height="30" /></a></li>
+        <li><a href="https://cocos.com" class="btn" target="_blank"><img src="https://forum.cocos.org/images/logo.png" height="30" /></a></li>
         <li><a href="#" class="btn autohide" onclick="toggleLanguage()">中文</a></li>
 {% for item in book.products %}
     {% if item.links %}
@@ -13,11 +13,11 @@
             <li><a href="{{entry.link}}" class="btn">{{entry.name}}</a></li>
             {% endfor %}
         </ul>
-    </li>                
+    </li>
     {% else %}
     <li><a href="{{item.link}}" class="btn autohide"><i class="fa fa-book"></i>{{item.name}}</a></li>
     {% endif %}
-{% endfor %}    
+{% endfor %}
 {% for item in book.version %}
     {% if item.links %}
     <li class="version-link">
@@ -27,11 +27,11 @@
             <li><a href="{{entry.link}}" class="btn">Version: <span style="font-weight:bold">{{entry.name}}</span></a></li>
             {% endfor %}
         </ul>
-    </li>                
+    </li>
     {% else %}
     <li><a href="{{item.link}}" class="btn">{{item.name}}</a></li>
     {% endif %}
-{% endfor %}   
+{% endfor %}
     </ul>
 </div>
 <div class="book-header" role="navigation">

en/_layouts/website/page.html

@@ -1,8 +1,8 @@
-{% extends template.self %}      
+{% extends template.self %}
 {% block book_sidebar %}
     <nav role="navigation" class="autoshow">
         <ul class="summary">
-        <li><a href="https://cocos.com" class="btn" target="_blank"><img src="https://forum.cocos.com/images/logo.png" height="30" /></a></li>
+        <li><a href="https://cocos.com" class="btn" target="_blank"><img src="https://forum.cocos.org/images/logo.png" height="30" /></a></li>
         <li><a href="#" class="btn" onclick="toggleLanguage()">中文</a></li>
         {% for item in book.version %}
         {% if item.links %}
@@ -13,11 +13,11 @@
                 <li><a href="{{entry.link}}" class="btn">Version: <span style="font-weight:bold; display: inline">{{entry.name}}</span></a></li>
                 {% endfor %}
             </ul>
-        </li>                
+        </li>
         {% else %}
         <li><a href="{{item.link}}" class="btn"></i>{{item.name}}</a></li>
         {% endif %}
-        {% endfor %}         
+        {% endfor %}
         {% for item in book.products %}
         {% if item.links %}
         <li>
@@ -27,11 +27,11 @@
                 <li><a href="{{entry.link}}" class="btn">{{entry.name}}</a></li>
                 {% endfor %}
             </ul>
-        </li>                
+        </li>
         {% else %}
         <li><a href="{{item.link}}" class="btn"><i class="fa fa-book"></i>{{item.name}}</a></li>
         {% endif %}
-    {% endfor %}      
+    {% endfor %}
         </ul>
     </nav>
     {{ super() }}
@@ -47,7 +47,7 @@
             } else if (path.indexOf('/en') !== -1) {
                 path = path.replace(/\/en[\/$\s]/i, '/zh/');
             }
-            // console.log('after: ' + path);    
+            // console.log('after: ' + path);
             location.assign(path);
     }
     </script>

zh/SUMMARY.md

@@ -120,9 +120,10 @@
 
 - [脚本指南及事件机制](scripting/index.md)
   - [脚本创建](scripting/setup.md)
-  - [语言支持](scripting/language-support.md)
   - [脚本基础](scripting/basic.md)
+  - [语言支持](scripting/language-support.md)
   - [ccclass](scripting/ccclass.md)
+  - [属性参数参考](scripting/reference/attributes.md)
   - [访问节点和其他组件](scripting/access-node-component.md)
   - [常用节点和组件接口](scripting/basic-node-api.md)
   - [生命周期回调](scripting/life-cycle-callbacks.md)
@@ -132,8 +133,6 @@
   - [使用计时器](scripting/scheduler.md)
   - [脚本执行顺序](scripting/execution-order.md)
   - [组件](scripting/component.md)
-  - [属性参数参考](scripting/reference/attributes.md)
-  - [CCClass 进阶参考](scripting/ccclass.md)
   - [事件机制](engine/event/index.md)
   - [插件脚本](scripting/plugin-scripts.md)
   - [添加 Log](scripting/log.md)
@@ -149,6 +148,7 @@
     - [精灵帧资源](asset/sprite-frame.md)
     - [立方体贴图资源](concepts/scene/skybox.md#cubemap)
     - [图像资源的自动裁剪](ui-system/components/engine/trim.md)
+    - [压缩纹理](asset/compress-texture.md)
     - [图集资源](asset/atlas.md)
     - [渲染纹理](asset/render-texture.md)
   - [预制资源](asset/prefab.md)

zh/_layouts/website/header.html

@@ -2,8 +2,8 @@
 {% block book_header %}
 <div class="cocos-navbar navbar-collapse" id="navbar" role="navigation">
     <ul class="nav navbar-nav">
-        <li><a href="https://cocos.com" class="btn" target="_blank"><img src="https://forum.cocos.com/images/logo.png" height="30" /></a></li>
-        <li><a href="#" class="btn autohide" onclick="toggleLanguage()">English</a></li>           
+        <li><a href="https://cocos.com" class="btn" target="_blank"><img src="https://forum.cocos.org/images/logo.png" height="30" /></a></li>
+        <li><a href="#" class="btn autohide" onclick="toggleLanguage()">English</a></li>
 {% for item in book.products %}
     {% if item.links %}
     <li>
@@ -13,11 +13,11 @@
             <li><a href="{{entry.link}}" class="btn">{{entry.name}}</a></li>
             {% endfor %}
         </ul>
-    </li>                
+    </li>
     {% else %}
     <li><a href="{{item.link}}" class="btn autohide"><i class="fa fa-book"></i>{{item.name}}</a></li>
     {% endif %}
-{% endfor %}    
+{% endfor %}
 {% for item in book.version %}
     {% if item.links %}
     <li class="version-link">
@@ -27,11 +27,11 @@
             <li><a href="{{entry.link}}" class="btn">Version: <span style="font-weight:bold">{{entry.name}}</span></a></li>
             {% endfor %}
         </ul>
-    </li>                
+    </li>
     {% else %}
     <li><a href="{{item.link}}" class="btn">{{item.name}}</a></li>
     {% endif %}
-{% endfor %}   
+{% endfor %}
     </ul>
 </div>
 <div class="book-header" role="navigation">

zh/_layouts/website/page.html

@@ -1,9 +1,9 @@
-{% extends template.self %}      
+{% extends template.self %}
 {% block book_sidebar %}
     <nav role="navigation" class="autoshow">
         <ul class="summary">
-        <li><a href="https://cocos.com" class="btn" target="_blank"><img src="https://forum.cocos.com/images/logo.png" height="30" /></a></li>
-        <li><a href="#" class="btn" onclick="toggleLanguage()">English</a></li>        
+        <li><a href="https://cocos.com" class="btn" target="_blank"><img src="https://forum.cocos.org/images/logo.png" height="30" /></a></li>
+        <li><a href="#" class="btn" onclick="toggleLanguage()">English</a></li>
         {% for item in book.version %}
         {% if item.links %}
         <li class="version-link">
@@ -13,11 +13,11 @@
                 <li><a href="{{entry.link}}" class="btn">Version: <span style="font-weight:bold; display: inline">{{entry.name}}</span></a></li>
                 {% endfor %}
             </ul>
-        </li>                
+        </li>
         {% else %}
         <li><a href="{{item.link}}" class="btn"></i>{{item.name}}</a></li>
         {% endif %}
-        {% endfor %}         
+        {% endfor %}
         {% for item in book.products %}
         {% if item.links %}
         <li>
@@ -27,11 +27,11 @@
                 <li><a href="{{entry.link}}" class="btn">{{entry.name}}</a></li>
                 {% endfor %}
             </ul>
-        </li>                
+        </li>
         {% else %}
         <li><a href="{{item.link}}" class="btn"><i class="fa fa-book"></i>{{item.name}}</a></li>
         {% endif %}
-    {% endfor %}      
+    {% endfor %}
         </ul>
     </nav>
     {{ super() }}
@@ -47,7 +47,7 @@
             } else if (path.indexOf('/en') !== -1) {
                 path = path.replace(/\/en[\/$\s]/i, '/zh/');
             }
-            // console.log('after: ' + path);    
+            // console.log('after: ' + path);
             location.assign(path);
     }
     </script>

zh/asset/compress-texture.md

@@ -0,0 +1,43 @@
+# 压缩纹理
+
+Cocos Creator 3D 可以直接在编辑器中设置纹理需要的压缩方式，然后在项目发布时自动对纹理进行压缩。针对 Web 平台，支持同时导出多种图片格式，引擎将根据不同的浏览器自动下载合适的格式。
+
+## 配置压缩纹理
+
+Cocos Creator 3D 支持导入多种格式的图片（具体见下表），但是在实际游戏运行中，我们不建议使用原始图片作为资源来加载。比如在手机平台上可能只需要原图 80% 或者更少的画质，又或者是没有使用到透明通道的 .png 可以将其转换成 .jpg，这样可以减少很大一部分图片的存储空间。
+
+图片格式 | Android | iOS | 微信小游戏 | Web
+------------ | ------------- | --------- | -------- | --------
+PNG | 支持 | 支持 | 支持 | 支持
+JPG | 支持 | 支持 | 支持 | 支持
+WEBP | Android 4.0 以上原生支持<br>其他版本可以使用 [解析库](https://github.com/alexey-pelykh/webp-android-backport) | 可以使用 [解析库](https://github.com/carsonmcdonald/WebP-iOS-example) | 不支持 | [部分支持](https://caniuse.com/#feat=webp)
+PVR | 不支持 | 支持 | 支持 iOS 设备 | 支持 iOS 设备
+ETC1 | 支持 | 不支持 | 支持 Android 设备 | 支持 Android 设备
+ETC2 | 只支持生成资源，引擎部分需要参考 pr 自己实现：<https://github.com/cocos-creator/cocos2d-x-lite/pull/1685>
+
+默认情况下 Cocos Creator 3D 在构建的时候输出的是原始图片，如果在构建时需要对某一张图片进行压缩，可以在 **资源管理器** 中选中这张图片，然后在 **属性管理器** 中对图片的纹理格式进行编辑。
+
+![compress-texture](compress-texture/compress-texture.png)
+
+## 压缩纹理详解
+
+如果想要使用压缩纹理，在构建项目的时候需要打开压缩纹理选项使项目使用压缩纹理功能：
+
+![compress-texture-build](compress-texture/compress-build.png)
+
+Cocos Creator 3D 在构建图片的时候，会查找当前图片是否进行了压缩纹理的配置，如果没有，则继续查找是否做了默认（Default）的配置，如果没有，则最后按原图输出。
+
+如果查找到了压缩纹理的配置，那么会按照找到的配置对图片进行纹理压缩。在一个平台中可以指定多种纹理格式，每种纹理格式在构建时都会根据原图压缩生成一张指定格式的图片。
+
+这些生成的图片不会都被加载到引擎中，引擎会根据 cc.macro.SUPPORT_TEXTURE_FORMATS 中的配置来选择加载合适格式的图片。`cc.macro.SUPPORT_TEXTURE_FORMATS` 列举了当前平台支持的所有图片格式，引擎加载图片时会从生成的图片中找到在这个列表中 **优先级靠前**（即排列靠前）的格式来加载。
+
+用户可以通过修改 `cc.macro.SUPPORT_TEXTURE_FORMATS` 来自定义平台的图片资源支持情况以及加载顺序的优先级。
+
+## 示例
+
+![1](compress-texture/compress-1.jpg)
+![2](compress-texture/compress-2.jpg)
+
+在上面的示例图中，默认平台配置了 png 格式的压缩纹理，web 平台配置了 pvr、png 格式的压缩纹理，而其他平台没有添加任何配置。那么在构建 web 平台的时候这张图片就会被压缩成 pvr，png 两种格式，在构建其他平台的时候则只会生成 png 格式的图片。
+
+而默认设置的 `cc.macro.SUPPORT_TEXTURE_FORMATS` 中只有 ios 平台上才添加了 .pvr 的支持，所以只有在 ios 的浏览器上才会加载 pvr 格式的图片，其他平台上的浏览器则加载 png 格式的图片。

zh/asset/compress-texture/compress-1.jpg

@@ -36,7 +36,7 @@
 
             const image = tr.appendChild(document.createElement('td')).
                 appendChild(document.createElement('img'));
-            image.src = "https://forum.cocos.com/images/logo.png";
+            image.src = "https://forum.cocos.org/images/logo.png";
 
             const slider = tr.appendChild(document.createElement('td')).
                 appendChild(document.createElement('input'));
@@ -57,7 +57,7 @@
         let duration = 3000;
         setInterval(() => {
             const timePast = Date.now() - firstTime;
-            const ratio = (timePast % duration) / duration; 
+            const ratio = (timePast % duration) / duration;
             for (const showcase of showcases) {
                 const mappedRatio = showcase.fx(ratio);
                 showcase.image.style.opacity = (1.0- mappedRatio);

zh/asset/compress-texture/compress-2.jpg

@@ -1,7 +1,7 @@
 
 ## cc 类
 
-将装饰器 [ccclass]() 应用在类上时，此类称为 cc 类。
+将装饰器 [ccclass](#ccclass) 应用在类上时，此类称为 cc 类。
 cc 类注入了额外的信息以控制 Cocos Creator 3D 对该类对象的序列化、编辑器对该类对象的展示等。
 
 ### ccclass
@@ -23,7 +23,7 @@ cc 类的各种特性是通过 `ccclass(name)` 的 cc 类选项参数来指定
 
 ## cc 属性
 
-当装饰器 [property]() 应用在 cc 类的属性或访问器上时，此属性称为 cc 属性。
+当装饰器 [property](#property) 应用在 cc 类的属性或访问器上时，此属性称为 cc 属性。
 与 cc 类类似，cc 属性注入了额外的信息以控制 Cocos Creator 3D 对该属性的序列化、编辑器对该属性的展示等。
 
 ### property
@@ -61,8 +61,9 @@ cc 属性的各种特性是通过 `property()` 的 cc 属性选项参数来指
 - 否则，属性的 cc 类型是**未定义**的。
 
 关于 cc 类型如何影响 cc 属性以及对未定义 cc 类型的属性的处理，见：
-- [编辑器和属性类型]()
-- [序列化]()
+
+- [属性类型](###属性参数)
+- [序列化参数](####serializable参数)
 
 下列代码演示了不同 cc 类型 的 cc 属性的声明：
 
@@ -112,7 +113,7 @@ CCClass 的构造函数使用 `constructor` 定义，为了保证反序列化能
 
 ```typescript
 class Sub extends Base {
-       
+
 }
 let sub = new Sub();
 console.log(sub instanceof Sub);  //true
@@ -171,20 +172,20 @@ obj.print();
 class Sprite{
     static count=0;
     static getBounds(){
-        
+
     }
 }
 ```
 
 静态成员会被子类继承，继承时会将父类的静态变量**浅拷贝**给子类，因此：
 
 ```typescript
-class Object{ 
+class Object{
     static count= 11;
     static range: { w: 100, h: 100 }
 }
 class Sprite extends Object{
-    
+
 }
 console.log(Sprite.count);    // 结果是 11，因为 count 继承自 Object 类
 
@@ -278,7 +279,7 @@ class Sprite {
 
 ### 属性参数
 
-#### <a name="default"></a>default 参数
+#### default参数
 
 `default` 用于声明属性的默认值，声明了默认值的属性会被 CCClass 实现为成员变量。默认值只有在**第一次创建**对象的时候才会用到，也就是说修改默认值时，并不会改变已添加到场景里的组件的当前值。
 
@@ -295,7 +296,7 @@ class Sprite {
     ```
 4. 空数组 `[]` 或空对象 `{}`
 
-#### <a name="visible"></a>visible 参数
+#### visible参数
 
 默认情况下，是否显示在 **属性检查器** 取决于属性名是否以下划线 `_` 开头。如果以下划线开头，则默认不显示在 **属性检查器**，否则默认显示。
 
@@ -313,7 +314,7 @@ class Sprite {
     private num = 0;
 ```
 
-#### <a name="serializable"></a>serializable 参数
+#### serializable参数
 
 指定了 `default` 默认值的属性默认情况下都会被序列化，序列化后就会将编辑器中设置好的值保存到场景等资源文件中，并且在加载场景时自动还原之前设置好的值。如果不想序列化，可以设置`serializable: false`。
 
@@ -322,7 +323,7 @@ class Sprite {
     private num = 0;
 ```
 
-#### <a name="type"></a>type 参数
+#### type参数
 
 当 `default` 不能提供足够详细的类型信息时，为了能在 **属性检查器** 显示正确的输入控件，就要用 `type` 显式声明具体的类型：
 
@@ -357,7 +358,7 @@ class Sprite {
     }
     ```
 
-#### <a name="override"></a>override 参数
+#### override参数
 
 所有属性都将被子类继承，如果子类要覆盖父类同名属性，需要显式设置 override 参数，否则会有重名警告：
 
@@ -372,7 +373,7 @@ private get name(){
 }
 ```
 
-更多参数内容请查阅 [属性参数](attributes.md)。
+更多参数内容请查阅 [属性参数](./reference/attributes.md)。
 
 ## GetSet 方法
 
@@ -462,7 +463,6 @@ set(value){
 }
 
 ```
-    
+
 > 如果没有和 get 一起定义，则 set 自身不能附带任何参数。<br>
 > 和 get 一样，设定了 set 以后，这个属性就不能被序列化，也不能指定默认值。
-