xiaokun/netease-modsdk-wiki
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

完整版BedrockWiki镜像！

Browse Source
This commit is contained in:
boybook
2025-03-20 11:52:46 +08:00
parent 1994c41f01
commit bf9aa4b056
214 changed files with 9042 additions and 8867 deletions
Download Patch File Download Diff File Expand all files Collapse all files

248
docs/wiki/guide/project-setup-android.md
View File

@@ -1,7 +1,7 @@
---
title: Project Setup Android
category: Guide
description: How to setup your project on Android
title: Android项目设置
category: 指南
description: 如何在Android平台上设置项目
mentions:
- Etanarvazac
- MedicalJewel105
@@ -10,74 +10,83 @@ mentions:
hidden: true
---
## Tools
# Android项目设置
It is not easy to find good apps to make add-ons for android platform, but we tried our best and collected Google Play apps for you.
For development on Android, you'll need a combination of 3 applications.
<!--@include: @/wiki/bedrock-wiki-mirror.md-->
1. A file manager that can create ZIP archives if your device is running Android 12 or newer.
2. A code editor (any text editor will work, but only code editors will show syntax highlights).
3. An image editor (no device comes with a editor that can go down to the pixels).
## 工具选择
### File Managers
为Android平台寻找合适的附加包开发工具并非易事，但我们已尽力为您收集了Google Play上的优质应用。Android开发需要以下三类工具组合使用：
These file managers are known to have ZIP archiving and view-only access to the `Android/data` folder:
1. **文件管理器**：若设备运行Android 12或更高版本，需支持创建ZIP压缩包
2. **代码编辑器**：任意文本编辑器均可，但专业编辑器能提供语法高亮
3. **图像编辑器**：需要支持像素级编辑（系统自带编辑器通常无法满足）
1. [**X-Plore**](https://play.google.com/store/apps/details?id=com.lonelycatgames.Xplore) - a powerful file manager with dual-pane tree view, a built-in text editor (not code), several file compression formats (ZIP, 7zip, RAR, etc.), and more. On rooted devices, X-Plore has edit access to `Android/data` and root directories.
2. [**Total Commander**](https://play.google.com/store/apps/details?id=com.ghisler.android.TotalCommander) - not as powerful out of the box compared to X-Plore, but contains some of the same features including dual pane, ZIP and RAR archives, and view-only access to `Android/data`. Total Commander has list view instead of tree and many other features that require plugins (apps from Google Play) to use.
### 文件管理器推荐
### Code Editors
以下管理器支持ZIP压缩包操作及`Android/data`目录只读访问：
1. **Acode:** [Free version](https://play.google.com/store/apps/details?id=com.foxdebug.acodefree) comes with ads that can be toggled off without paying. Supports GitHub integration using a Personal Access Token, FTP/SFTP, syntax highlighting for over 100+ languages including JSON, tab-view for multi-file editing, dozens of themes, and more. This app is open source and does have a [paid version](https://play.google.com/store/apps/details?id=com.foxdebug.acode) that allows a much deeper theme customization.
1. [**X-Plore**](https://play.google.com/store/apps/details?id=com.lonelycatgames.Xplore) - 双面板树形视图，内置文本编辑器（非代码专用），支持ZIP/7zip/RAR等格式。Root设备可编辑`Android/data`及系统目录
2. [**Total Commander**](https://play.google.com/store/apps/details?id=com.ghisler.android.TotalCommander) - 双面板界面，支持ZIP/RAR压缩包，列表视图展示文件，部分功能需插件扩展
### 代码编辑器推荐
1. **Acode**：
- [免费版](https://play.google.com/store/apps/details?id=com.foxdebug.acodefree) 含可关闭的广告
- 支持GitHub集成（需个人访问令牌）、FTP/SFTP协议
- 提供100+语言语法高亮（含JSON）、多标签编辑、丰富主题
- 开源项目，另有[付费版](https://play.google.com/store/apps/details?id=com.foxdebug.acode)支持深度主题定制
:::info
Acode is the only powerful code editor actively being developed on Android at this time. Other editors are very limited or have been abandoned long enough to vanish from the Google Play store. If you know of a code application, you can contribute to this guide.
Acode是当前Android平台唯一持续更新的专业代码编辑器。其他编辑器功能有限或已停止维护。若您有其他推荐，欢迎贡献至本指南。
:::
### Image Editors
### 图像编辑器推荐
1. [**Pocket Paint**](https://play.google.com/store/apps/details?id=org.catrobat.paintroid) - lightweight editor with the bare minimum features needed for any add-on creation. This app is easy to use and allows importing other images over others. Saves in JPG (compressed), PNG (lossless, with transparency), and ORA (multi-layer images). This app is open source.
2. [**Pixly**](https://play.google.com/store/apps/details?id=com.meltinglogic.pixly&hl=en) - very lightweight, no ads or in app purchases. Plentiful tools and customizable brushes, ability to save palettes internally or externally.
3. [**Pixel Art editor**](https://play.google.com/store/apps/details?id=net.spc.app.pixelarteditor&hl=en) - a simple lightweight app. Would be the best if you need just to draw some texture-placeholder.
1. [**Pocket Paint**](https://play.google.com/store/apps/details?id=org.catrobat.paintroid) - 轻量级基础编辑器，支持JPG/PNG/ORA格式，开源项目
2. [**Pixly**](https://play.google.com/store/apps/details?id=com.meltinglogic.pixly&hl=en) - 无广告内购，提供丰富笔刷工具和调色板管理
3. [**Pixel Art editor**](https://play.google.com/store/apps/details?id=net.spc.app.pixelarteditor&hl=en) - 极简像素画工具，适合制作纹理占位图
## Your Workspace
## 工作区搭建
:::tip
In this version of the guide, "BP" refers to your behaviour pack folder and "RP" refers to your resource pack folder in your workspace. For locations in files or directories, `../<current location>` indicates "From last location" followed by the added space (e.g.: `/one/two/three/file.txt` would be shortened to `../three/file.txt`)
本文中：
- "BP"指行为包目录
- "RP"指资源包目录
- 路径表示`../<当前位置>`指代上级路径（如`/one/two/three/file.txt`简写为`../three/file.txt`）
If your device is rooted, you can follow the main project setup using the `/Android/data/com.mojang.minecraftpe/files/games/com.mojang` development behaviour and resource pack folders directly. Otherwise, follow the steps below.
若设备已Root，可直接使用`/Android/data/com.mojang.minecraftpe/files/games/com.mojang`开发目录。未Root设备请按以下步骤操作。
:::
Before we begin, you need a workspace. Using your file manager, navigate to your Internal Storage (In most cases, it's `/`. In others, the full path (e.g.: `/storage/emulated/0/`) is displayed. Both are acceptable.) and create a folder that will contain your packs. For this example, our full directory is `/Minecraft Packs/MyFirstAddon`. From there, you'll need one folder for both your behaviour and resource packs (e.g.: `../MyFirstAddon/addonBP` and `../MyFirstAddon/addonRP`).
1. 使用文件管理器进入内部存储（通常为根目录`/`或`/storage/emulated/0/`）
2. 创建项目总目录（示例：`/Minecraft附加包/我的首个附加包`）
3. 在总目录下分别建立行为包和资源包子目录（示例：`../我的首个附加包/addonBP`和`../我的首个附加包/addonRP`）
Now that you have the workplace setup, code editors should have a way for you to open a folder as a workplace. In this guide, we'll be walking through Acode.
以Acode为例配置工作区：
1. Open Acode.
2. Tap the file browser button (3 bars in the top-left), followed by "Open folder"
3. Tap "Add a storage", followed by "select folder"
4. This should have opened your device's file browser. Navigate to the _main_ folder for your projects (for us, `/Minecraft Packs`) then tap "Use this folder". If your device asked you to allow Acode access, tap "Allow".
5. You should be back in Acode now. Tap "OK" and your folder should now be in the list. Tap on it and then "Select Folder" on the bottom of the screen.
6. Now when you open the file browser (3 bars in top-left), you should see your folder in the list. You now have quick access to your addon's behaviour and resource pack folders. The file browser uses tree view to display your active workspace.
1. 打开Acode点击左上角文件浏览器图标
2. 选择"打开文件夹" → "添加存储" → "选择文件夹"
3. 导航至项目总目录（如`/Minecraft附加包`）并授权访问
4. 完成配置后即可在侧边栏快速访问项目文件
:::tip
You can create new files and folders inside your packs from the file browser by tapping and holding on the folder you want to create the item in.
长按目录可快速新建文件/文件夹，建议保持整洁的项目结构。
:::
## BP & RP Manifests
## 清单文件配置
:::warning
From here on out, all files and folders have very specific names unless otherwise noted. Wrongly named files and/or folders are a common reason of an error. Please ensure you're checking your work carefully in accordance to the examples provided. If a file or folder mentioned has not yet been created, please create it in it's appropriate directory.
When creating a new file in a file manager or some text or code applications, the `.txt` extension is added automatically to the end of the file name. To ensure our files work as intended, be sure to remove `.txt`. Like names, the wrong file extension is also a common reason of an error. If you're using Acode, you'll notice `untitled.txt` is completely highlighted instead of just `untitled`. This is a common practice for naming programming language files.
注意：
- 所有文件/文件夹名称需严格匹配示例
- 错误命名是常见报错原因
- 新建文件时注意移除自动添加的`.txt`扩展名
- Acode中`untitled.txt`会全选文件名，便于修改扩展名
:::
The manifest file is the file Minecraft uses to identify your packs. Every pack has one (and only one) manifest. A folder with a correctly formatted manifest will show up in Minecraft. Before we begin adding content, we will ensure our "minimal" pack is visible. Manifests are written in the `JSON` programming language. If you're unfamiliar with JSON, you can learn more about it [here](/guide/understanding-json).
每个附加包都需要唯一的`manifest.json`清单文件。以下是基本配置模板：
Create a new text file in your addon's behaviour pack folder called `manifest.json`. To begin, copy and paste the following code into the `manifest.json` file. A full breakdown of the manifest file is provided after creating these files.
<codeHeader>BP/manifest.json</codeHeader>
```json
::: code-group
```json [BP/manifest.json]
{
"format_version": 2,
"header": {
@@ -97,14 +106,10 @@ Create a new text file in your addon's behaviour pack folder called `manifest.js
}
```
Now create another `manifest.json` file in your addon's resource pack folder. Again, copy and paste the following code inside the new file.
<codeHeader>RP/manifest.json</codeHeader>
```json
```json [RP/manifest.json]
{
"format_version": 2,
"header" {
"header": {
"name": "pack.name",
"description": "pack.description",
"uuid": "...",
@@ -120,110 +125,99 @@ Now create another `manifest.json` file in your addon's resource pack folder. Ag
]
}
```
:::
## Manifest Breakdown
### 清单参数说明
- `format_version` defines the version the syntax your manifest is written in. Version 2 is the most recent stable version. Always use this version.
- `name` is name of your pack. We will be defining the this in "code form" later so they can easily be translated into other languages, should you create a pack with multiple languages.
- `description` is a short description about your pack that will show up under the `name` in-game. This will also be defined later in "code form".
- `uuid` is required to help identify your pack from other packs and will have a breakdown of it's own below. Once explained, you'll need to replace all of the `...` with them.
- `version` is literally the version of your addon. Upon completing your addon, you can always change this to `[1, 0, 0]`. However, it'll be easier to use the hotfix spot while making your changes on mobile.
- `min_engine_version` tells Minecraft what the minimum version it needs to be in order for your pack to work. For example, if your pack has a crafting recipe that involves concrete, your pack can't run on Minecraft 1.5 because concrete doesn't exist in that version.
- Under `modules`, you have the `type` field. This tells Minecraft what your pack is. So `data` in your BP tells the game that pack is a behaviour pack and `resources` in your RP tells the game that pack is a resource pack.
| 参数 | 说明 |
|----------------------|----------------------------------------------------------------------|
| `format_version` | 清单语法版本（推荐使用2） |
| `name` | 包名称（后续通过语言文件定义） |
| `description` | 包描述（显示在游戏内名称下方） |
| `uuid` | 唯一标识符（需使用UUIDv4生成） |
| `version` | 附加包版本号（格式[主,次,修订]） |
| `min_engine_version` | 最低兼容游戏版本 |
| `modules.type` | 包类型：`data`=行为包，`resources`=资源包 |
## UUID Breakdown
### UUID生成指南
A UUID, or **U**niversally **U**nique **ID**entifier, both identifies your pack for other programs (Minecraft, for example) and separates your pack from someone else's pack for the program it's for. A version 4 UUID (UUID-4) is usually in the format `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` and made of a random string of letters and numbers. For example: `5c830391-0937-44d6-9774-406de66b6984`.
UUID（通用唯一识别码）格式为`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`，需使用[在线生成工具](https://www.uuidgenerator.net/version4)创建版本4的随机UUID。每个清单文件需要两个不同的UUID，共需生成4个唯一值。
You should **NEVER** use the same UUID twice! Use the [Online UUID Generator Tool](https://www.uuidgenerator.net/version4) to generate the UUID's needed for your manifest files. Every manifest file uses two different UUID's. So to ensure your packs will work correctly, get 4 different UUID's to replace all of the `...` in both manifests. When finished, each UUID entry should look similar like this: `"uuid": "5c830391-0937-44d6-9774-406de66b6984`
## 包图标配置
## Pack Icon
为附加包添加识别图标（建议64x64 PNG格式），将图片命名为`pack_icon.png`并放置于两个包的根目录：
Notice how other packs have a icon? It's a image file which can quickly identify how your addon will appear in-game. Got a low-resolution square image as a PNG? You can use it! Otherwise, you can use this example icon.
<WikiImage src="/assets/images/guide/project-setup/pack_icon.png" alt="Pack Icon" pixelated/>
<WikiImage src="/assets/images/guide/project-setup/pack_icon.png" alt="包图标示例" pixelated/>
<BButton
link="/assets/images/guide/project-setup/pack_icon.png" download
color=default
>Download Image</BButton>
>下载示例图标</BButton>
You must place a copy of your desired image in both the behaviour and resource packs. In order for the image to be read correctly, the name must be `pack_icon.png`.
## 多语言配置
## Language Files
在以下路径创建语言文件，使用`§`符号实现文字格式化（格式代码参考[Minecraft颜色代码](https://htmlcolorcodes.com/minecraft-color-codes/)）：
Remember when we said we'll define the pack name and description in code form earlier? Now is that time as it's the last thing we need to do to setup your addon. You will need to create 4 new files and 2 new folders (2 files and 1 folder for each pack). You can You can learn more about how Minecraft handles localization [here](/concepts/text-and-translations). You can also format your definitions using the `§` symbol. You can view a list of colors and formats [here](https://htmlcolorcodes.com/minecraft-color-codes/). If you use any formatting, make sure you `§r`eset when changing formats: `§kl My pack l` will render "My pack" unreadable whereas `§kl §rMy pack §kl` can be read properly.
<codeHeader>BP/texts/en_US.lang</codeHeader>
```
pack.name=§2My §lFIRST §r§2Addon's Behaviour Pack!
pack.description=This addon is made by a Wiki Contributor!
::: code-group
```txt [BP/texts/en_US.lang]
pack.name=§2我的§l首个§r§2行为包！
pack.description=本附加包由Wiki贡献者制作！
```
<codeHeader>BP/texts/languages.json</codeHeader>
```json
```json [BP/texts/languages.json]
["en_US"]
```
<codeHeader>RP/texts/en_US.lang</codeHeader>
```
pack.name=§2My §lFIRST §r§2Addon's Resource Pack!
pack.description=This addon is made by a Wiki Contributor!
```txt [RP/texts/en_US.lang]
pack.name=§2我的§l首个§r§2资源包！
pack.description=本附加包由Wiki贡献者制作！
```
<codeHeader>RP/texts/languages.json</codeHeader>
```json
```json [RP/texts/languages.json]
["en_US"]
```
:::
## Importing Your Addon
## 导入附加包
Now that your addon has all of the required content, we need to import it to Minecraft. To do this, we need to create a file with the extension `.mcaddon`.
1. 选中行为包和资源包目录
2. 创建ZIP压缩包
3. 重命名文件扩展名为`.mcaddon`
4. 点击生成的文件自动导入游戏
1. Open your preferred file manager and navigate to the folder containing your behaviour and resource packs.
2. Using multi-select, select both packs and create a ZIP file.
3. When asked for the name of the file, ensure that `.zip` is changed to `.mcaddon`.
![](/assets/images/guide/project-setup-android/zip-addon.png)
4. When your file manager finishes, it should be a `MCADDON` file with Minecraft as it's icon. Tapping on this file should launch Minecraft.
![](/assets/images/guide/project-setup-android/zip-addon.png)
If done correctly, Minecraft will display a banner for both packs. First is `Importing...`. After should be `Successfully imported "<your pack name>"`. You can also go to `Settings > Storage` if you don't see the import messages to verify your packs were imported. If you do not see either pack, check out our [troubleshooting guide](/guide/troubleshooting).
导入成功后游戏会显示提示横幅，或在`设置 > 存储`中确认包状态。若导入失败请参考[问题排查指南](/wiki/guide/troubleshooting)。
## Turn on Content Log
## 开启内容日志
:::warning
Content log is the most useful tool you have for debugging your addons. Please do not skip this step.
内容日志是调试附加包的重要工具，请务必开启
:::
![](/assets/images/guide/content_log.png)
Content Log is an extremely important debugging tool, which you should always have on.
1. 进入`设置 > 创作者`
2. 启用两个内容日志选项
3. 游戏中按`Ctrl+H`可打开日志界面
Turn on both content log settings in `settings > creator`. This will show you any errors in your add-on when you enter a world with it applied. You can also open the content log GUI in-game by pressing `ctrl+h`. Learn more about the content log [here](/guide/troubleshooting).
## 创建测试世界
## Creating your testing world
1. 点击**创建新世界**
2. 确保以下设置：
- 实验性玩法：全部开启
- 默认游戏模式：创造模式
- 世界权限：仅邀请（单人游戏不影响）
![](/assets/images/guide/project-setup/settings_1.png)
![](/assets/images/guide/project-setup/settings_2.png)
Now we create a world to test your new add-on!
3. 激活行为包与资源包
4. 点击**创建**
1. Click "**Create new world**";
## 最终项目结构
2. Ensure that the following settings are set.
![](/assets/images/guide/project-setup/settings_1.png)
![](/assets/images/guide/project-setup/settings_2.png)
3. Now activate your behavior pack, and your resource pack. You can do this by selecting the packs, and clicking 'apply'.
4. Now click '**Create**'!
## Final Notes
**Here is how your project should look, after completing this page:**
Remember that in future, we will represent `com.mojang/development_behavior_packs/guide_RP/` as `RP`, and `com.mojang/development_behavior_packs/guide_BP/` as `BP`.
完成配置后项目应包含以下文件：
<FolderView :paths="[
'com.mojang/development_resource_packs/guide_RP/manifest.json',
@@ -236,26 +230,26 @@ Remember that in future, we will represent `com.mojang/development_behavior_pack
'com.mojang/development_behavior_packs/guide_BP/texts/languages.json',
]"></FolderView>
## What you have learned
## 学习总结
:::tip What you have learned:
:::tip 已掌握内容：
- What and where your `com.mojang` folder is and what it contains
- How to setup your mobile workspace
- What a `manifest.json` file is
- What are UUID's and how to use them
- How to create icons for your addons
- What a `.lang` file is
- `com.mojang`目录结构解析
- 移动端工作区配置方法
- 清单文件的作用与配置
- UUID的生成与应用
- 包图标的制作规范
- 语言文件的配置原理
:::
## Your progress so far
## 进度追踪
<Checklist>
- [x] Setup your pack
- [ ] Create a custom item
- [ ] Create a custom entity
- [ ] Create a custom block
- [x] 完成项目基础配置
- [ ] 创建自定义物品
- [ ] 创建自定义实体
- [ ] 创建自定义方块
</Checklist>
</Checklist>