39. 客户端支持Part 2: 客户端资源¶

很多情况下，游戏客户端所需的策划数据、图表文件、asset bundle等资源文件是与客户端共同发布的。然而，这些数据在游戏运营的过程中随时可能发生变更，而为了更新这些数据而每次都发布新的客户端是一件相当有压力的事情。因此，通常会从外部获取游戏客户端使用的资源文件。

一般情况下，为了从外部获取文件，客户端会先计算须要获取的文件的列表和 MD5等checksum值，然后在接收这些文件后确认这些文件与自身当前拥有的资源文件信息是否一致。若文件已被添加或已被删除，或是文件的 checksum值有异时，客户端会删除不再需要的文件，并接收新的文件，保存在客户端设备中。

iFun Engine提供了客户端资源管理功能，以便能够轻松处理这些开发过程。使用该服务后，可以不用更新客户端，并直接添加、删除或变更客户端资源。

在服务器的 MANIFEST.json 中进行简单的设置，即可使用客户端资源服务。该服务在HTTP协议上运行。

39.1. 设置客户端资源提供服务¶

39.1.1. 方法 1: 无需单独的Web服务器，由游戏服务器处理资源请求时¶

39.1.1.1. 指定资源目录¶

如果最上级的源目录下不存在名为 client_data 的目录，创建一个即可。然后将客户端须要下载的文件复制到其中。

若最上级 CMakeLists.txt 的 RESOURCE_DIRS 项目中不存在 client_data ，则按如下所示添加。

...
set(RESOURCE_DIRS game_data client_data src/json_protocols)
...

Tip

当已经 make package ，但client_data目录未被同时打包时，请检查上面的CMakeLists.txt设置。具体内容请参考将游戏资源文件包含在package中。

39.1.1.2. 设置MANIFEST.json¶

按如下所示，设置MANIFEST.json。

{
  ...
  "ClientResourceService": {
    "use_client_resource_service" : true,

    "client_resource_service_port" : 8020,

    "client_resource_dir" : "client_data",
    "client_resource_url_base": "",
    "client_resource_list_url": "",

    "client_resource_service_threads_size": 2,

    "client_resource_max_file_size": "1000000",
  }
  ...
}

现在iFun引擎在游戏服务器启动时，会自动计算相应文件夹下存在的文件的MD5，并利用该信息在内部创建资源列表。同时，直接处理用于下载各个资源文件的HTTP请求。

39.1.1.3. .funignore 파일 및 규칙¶

아이펀 엔진은 client_data 디렉토리 안에 포함된 파일 중 일부를 무시할 수 있는 기능을 지원합니다. 만약 디렉토리 안에 민감한 정보를 가진 파일이 있거나 빌드 과정에서 임시 파일이 생성되는 경우 이 기능을 통해 필요한 파일만 외부로 노출시킬 수 있습니다.

비활성화 규칙은 엔진에서 새 프로젝트를 생성할 때 client_data 디렉토리 안에 생성되는 .funignore 파일을 통해 지정할 수 있으며, Perl 정규 표현식 패턴과 일치하는 파일들을 모두 비활성화 하여 다운로드할 수 없도록 합니다.

기본적으로 생성되는 .funignore 파일은 다음과 같은 정규 표현식을 포함하고 있으며 # 또는 ``//``를 사용해 주석을 달 수 있습니다.

# 'data/specific.txt' 패턴과 일치하는 모든 파일을 무시 합니다.
.+data/specific\.txt

# 아래에 지정된 디렉토리에 포함된 파일 및 하위 디렉토리를 모두 무시하며 규칙의 적용 범위는
# 최상단 디렉토리부터 각 하위 디렉토리까지 입니다.
\.svn
\.git

# 아래 패턴과 일치하는 파일을 모두 무시합니다. 이 패턴들은 다양한 운영체제와 IDE 에서
# 범용적으로 사용되는 파일 형식이며 규칙 적용 범위는 최상단 디렉토리부터 각 하위
# 디렉토리까지 입니다.
\.DS_Store
Thumb\.db
Desktop\.ini
^[\w\s\.,-_]+\.bak
^[\w\s\.,-_]+\.log
[Bb]in
[Oo]bj
[Bb]uilds?

# Vim 임시 파일
^[\w\s\.,-_]+\.sw[ponm]

# 파이썬
venv
pip-log\.txt
^[\w\s\.,-_]+\.py[co]

39.1.2. 方法 2: 由单独的Web服务器处理资源请求时¶

当指定了 MANIFEST.json 的 client_resource_list_url 和 client_resource_url_base 时，iFun引擎可以通过外部Web服务器对资源列表请求和各资源文件的请求进行redirect。

39.1.2.1. 创建资源列表文件¶

按如下所示，执行命令。第一个参数为资源所在根文件夹路径，第二个参数为要创建的资源列表文件路径。

$ funapi_client_resource_generator <path/to/resource/base> <path/to/list.json>

将创建好的文件复制到外部Web服务器中。然后在 MANIFEST.json 的 client_resource_list_url 中指定相应文件的URL。

39.1.2.2. 将资源文件复制到Web服务器¶

现在将包含资源文件的文件夹复制到外部Web服务器中。然后在 client_resource_url_base 中指定相应目录的URL。

39.1.2.3. 设置MANIFEST.json¶

{
  ...
  "ClientResourceService": {
    "use_client_resource_service" : true,

    "client_resource_service_port" : 8020,

    "client_resource_dir" : "",
    "client_resource_url_base": "http://my.cdn.com:80/path/to/resource/base/",
    "client_resource_list_url": "http://my.cdn.com:80/path/to/list.json",

    "client_resource_service_threads_size": 2,

    "client_resource_max_file_size": "1000000",
  }
  ...
}

现在游戏服务器启动时，iFun引擎会从 client_resource_list_url 获取资源列表文件并caching，当收到各资源文件的请求时，将通过 client_resource_url_base 进行redirect。

39.1.2.4. .funignore 파일 및 규칙¶

.funignore 파일은 funapi_client_resource_generator 프로그램을 실행할 때도 동일하게 적용되며 Perl 정규 표현식과 일치하는 모든 디렉토리 또는 파일을 목록에서 제외시킵니다.

39.1.3. 更新资源信息¶

在服务器正在运行的状态下，也可以更新资源文件。

在代码中调用以下方法即可。

ClientResourceService::Reload();

ClientResourceService.Reload();

Note

如果游戏服务器具有直接分发资源文件的作用，那么iFun引擎将针对 client_data 的文件重新计算MD5。同时，如果已指定外部HTTP，且已指定 client_resource_list_url ，那么将从相应URL上下载已保存了MD5的文件，储存在内存中，并对其进行应用。

Note

即使重新计算MD5，也不会向正在游戏的用户传输新的资源文件。需要注意的是，当更新资源文件时，正在游戏中的用户和刚访问游戏的用户之间会出现拥有不同资源数据的情况。

39.2. 示例: 应用外部Web服务器时¶

下面是存在data/items.json和data/stages.json资源文件时，将两个文件通过外部Web服务器传输给客户端的示例。

39.2.1. 获取资源列表¶

在Web浏览器中输入 http://localhost:8020 。将出现如下类似结果。

{
  data: [
    {
    path: "data/items.json",
    size: 2042,
    md5: "d41d8cd98f00b204e9800998ecf8427e"
    },
    {
    path: "data/stages.json",
    size: 2044527,
    md5: "9ab9626a301c2bf1444893a69a1bfac7",
    md5_front: "8fdd96188cadababf2fbcb812b43e6fb"
    }
  ],
  url: "http://my.cdn.com:80/path/to/resource/base/"
}

Tip

md5_front 是文件初始1MB部分的md5值。它是为了防止客户端连大文件的MD5也一同计算。如果初始1MB容量的MD5不同时，将直接开始下载。若md5_front相同，则继续对所有文件计算MD5。该字段仅针对大于1MB的文件创建。

39.2.2. 获取各资源文件¶

在浏览器中输入 http://localhost:8020/data/items.json 后，iFun引擎将通过 http://my.cdn.com:80/path/to/resource/base/data/items.json 进行redirect，并下载文件。

39.3. 客户端代码¶

client资源服务的客户端已在iFun引擎客户端插件中实现。

插件会自动请求MD5 list，确认其中是否存在文件，并与自身拥有的MD5进行比较后，下载已更新或已添加的文件，删除已删除的文件。为了快速进行MD5计算，会缓存已计算的MD5文件。

更详细的内容请参考客户端支持Part 1: 插件。

39.4. 客户端资源信息提供服务的参数设置¶

可以在MANIFEST.json的 ClientResourceService 会话中设置如下值。

通用设置:

use_client_resource_service: 是否激活功能 (type=bool, default=false)
client_resource_service_port: 客户端资源服务要binding的HTTP端口。(type=uint64, default=0)
client_resource_max_file_size: 一个客户端资源文件的最大容量。单位为字节。若存在大于该容量的文件，游戏服务器将不会运行。(type=uint64, default=10485760)

无需Web服务器，直接由游戏服务器处理时:

client_resource_dir: Client下载资源的保存目录路径。(type=string, default=””)

使用单独的Web服务器时:

client_resource_list_url: 包含客户端资源列表的文件URL。对于列表文件的创建，请参考创建资源列表文件。(type=string, default=””)
client_resource_url_base: 用于接收客户端资源的Base URL（例如CDN base路径）。若已被设置，则客户端资源服务仅向客户端传输文件列表，实际的文件将通过redirect的方式从相应的URL获取。输入该值后，将忽略 client_resource_dir 值，并且必须存在 client_resource_list_url 。(type=string, default=””)

几乎不需要直接更改设置的参数

client_resource_service_threads_size: 分配到客户端资源服务中的线程个数。(type=uint64, default=2)