MegaBlock_Basic¶
Attention
The content of this page will be updated soon.
Note
This sample supports AR Foundation (it can also work without AR Foundation). If you want to use AR Foundation, please refer to AR Foundation Configuration for configuration.
Demonstrates how to use the basic features of Mega, import Blocks using tools, place 3D content, and finally run to view tracking effects.
Configuration and Running¶
Please refer to Mega Unity Sample Usage Guide for configuration and running instructions.
Running Effect
How to Use¶
How It Works¶
This sample can be code-free, but it is generally not recommended. The only purpose of the code in the script is to prompt the end user for specific system states.
How is the scene created?¶
The section Create an EasyAR Mega Scene from Scratch in Mega Unity introduces the creation of EasyAR-related features in the scene.
Where is the 3D model?¶
No 3D models are provided in the scene. If you do not create or add models yourself, only the camera view will be displayed at runtime. You need to place 3D models according to the description in the Mega Unity Sample Usage Guide and the Blocks imported by the tool.
What is diagnostic information?¶
At runtime, you will find that the positioning information is constantly updating, which means the application is continuously communicating with the server. This is the foundation for Mega to run. Generally, you should not close this connection, and disconnecting from the server during use will greatly affect Mega’s performance.
Displaying and monitoring diagnostic information during development is extremely helpful. It helps you understand the basic operation of the system and enables effective communication with the EasyAR team when reporting issues.
Important
Please read Message Output carefully and consider what configuration and control switches to use during development, testing, and after the application goes live. Note that communication with EasyAR usually requires providing this information, so it is recommended to make full use of it rather than disabling it immediately.
How to determine if the device is not supported¶
When the device is not supported, the session state will be Broken. You need to handle this situation and provide appropriate prompts. If needed, you can also refer to Workflow_ARSession and ARSession Workflow to make this judgment before ARSession starts.
private void HandleSessionStateChange(ARSession.SessionState status)
{
if (status == ARSession.SessionState.Broken)
{
if (Session.Report.BrokenReason == SessionReport.SessionBrokenReason.NoAvailabileFrameSource || Session.Report.BrokenReason == SessionReport.SessionBrokenReason.FrameFilterNotAvailabile)
{
ShowMessage(100,
Session.Report.Exception + Environment.NewLine +
$"EasyAR Session Broken with reason {Session.Report.BrokenReason}." + Environment.NewLine +
"Strictly, it means the device is not supported by EasyAR with (and only with) your configurations (features and settings you choose in the session object)." + Environment.NewLine +
$"Configurations you need to examine include but not limited to if there are missing/extra frame source/filter objects under the session, options like {nameof(ARSession)}.{nameof(ARSession.AssembleOptions)} and {nameof(MegaTrackerFrameFilter)}.{nameof(MegaTrackerFrameFilter.MinInputFrameLevel)}, etc.." + Environment.NewLine +
$"You can get detailed availability report from {nameof(ARSession)}.{nameof(ARSession.Report)}." + Environment.NewLine +
$"The session may recover automatically if the device list updated from online data during session start and found device supported." + Environment.NewLine +
$"EasyAR Session 损坏（原因：{Session.Report.BrokenReason}）。" + Environment.NewLine +
"严格来说，这意味着你配置（且仅该配置）下的EasyAR无法在该设备上运行。配置指你在session物体中所选择的功能和设置。" + Environment.NewLine +
$"你需要检查的配置包括但不限于，session下是否有缺失或多余的frame source/filter物体，一些选项比如{nameof(ARSession)}.{nameof(ARSession.AssembleOptions)}，{nameof(MegaTrackerFrameFilter)}.{nameof(MegaTrackerFrameFilter.MinInputFrameLevel)}等。" + Environment.NewLine +
$"你可以从{nameof(ARSession)}.{nameof(ARSession.Report)}获得详细的可用性报告。" + Environment.NewLine +
$"如果在启动session时联网更新设备列表时发现设备已被支持，session有可能自动恢复。"
,
$"EasyAR Session Broken with reason {Session.Report.BrokenReason}." + Environment.NewLine +
"The EasyAR features selected by the App developer cannot run on your device." + Environment.NewLine +
$"EasyAR Session 损坏（原因：{Session.Report.BrokenReason}）。" + Environment.NewLine +
"应用开发者选择的EasyAR功能无法在你的设备上运行。"
);
}
else
{
ShowMessage(100,
Session.Report.Exception + Environment.NewLine +
$"EasyAR Session Broken with reason {Session.Report.BrokenReason}." + Environment.NewLine +
"This is usually device-irrelevant, Please debug your project using exception details." + Environment.NewLine +
$"EasyAR Session 损坏（原因：{Session.Report.BrokenReason}）。" + Environment.NewLine +
"这通常是设备无关的，请使用详细异常信息调试你的工程。"
,
$"EasyAR Session Broken with reason {Session.Report.BrokenReason}, please ask the app developer for help." + Environment.NewLine +
$"EasyAR Session 损坏（原因：{Session.Report.BrokenReason}），请向应用开发者寻求帮助。"
);
}
}
}
Normal service states that need to be handled properly¶
This sample shows how to obtain service state changes and handle them properly.
Get status change information
megaTracker.LocalizationRespond += HandleLocalizationStatusChange;
This information is returned by the Mega localization service. It is not updated every frame, but it reflects the server connection status, whether localization is successful, etc.
Handle specific status changes and prompt the end user
private void HandleLocalizationStatusChange(MegaLocalizationResponse response)
{
var status = response.Status;
wakingUpCount = status == MegaTrackerLocalizationStatus.WakingUp ? wakingUpCount + 1 : 0;
if (wakingUpCount >= 5)
{
ShowMessage(10,
"Service is waking up, you need to let user wait." + Environment.NewLine +
"服务正在唤醒中，你需要让用户等待。"
,
"Service is waking up, please wait patiently." + Environment.NewLine +
"服务正在唤醒中，请耐心等待。"
);
}
if (status == MegaTrackerLocalizationStatus.QpsLimitExceeded)
{
ShowMessage(10,
"QPS limit exceeded, you can keep random user fail (overall worse tracking quality) or pay for more QPS." + Environment.NewLine +
"QPS超限，你可以保持随机用户失败（总体跟踪质量下降）或付费提升QPS上限。"
,
"Too many users, please wait patiently." + Environment.NewLine +
"用户过多，请耐心等待。"
);
}
if (status == MegaTrackerLocalizationStatus.ApiTokenExpired)
{
ShowMessage(10,
"Token expired (may only occurs when you access the service using a Token)." + Environment.NewLine +
"You need to request a Token from your own backend and call MegaTrackerFrameFilter.UpdateToken to update it. Your backend should generate the Token using EasyAR's Token generation method." + Environment.NewLine +
"Token过期（仅在你使用Token访问服务时可能出现）。" + Environment.NewLine +
$"你需要请求你自己的后台获取Token，并调用MegaTrackerFrameFilter.UpdateToken进行更新。你的后台应使用EasyAR的Token生成方式生成Token。"
,
"<Instructions from App developer to user.>" + Environment.NewLine +
"<应用开发者对用户的说明。>"
);
}
}
You need to handle the QpsLimitExceeded and WakingUp states and prompt the end user appropriately. The sample text is for reference.
QpsLimitExceeded
If you encounter this state, it usually means too many devices are accessing the service. EasyAR Mega service is charged by Qps. Note that this value is not concurrency; typically, with default configuration, device requests are 1FPS, so the Qps value is roughly equal to the number of concurrent devices. Due to network fluctuations, it is normal for this state to appear when the total number of devices is close to but not reaching the limit.
If a device encounters this state, its tracking performance will be affected. If this state persists, tracking will be performed entirely on the device, and the effect will be greatly reduced.
If a device encounters this state, other devices accessing the service may also encounter the same state. The specific devices and timing are completely random, similar to a ticket-grabbing process.
Service quality is guaranteed when Qps is exceeded, but tracking performance on the device is not guaranteed. You need to purchase more Qps to support your application. If you need to temporarily increase Qps support (over 50), you must contact EasyAR business at least two working days in advance.
When Qps is exceeded, it is recommended to remind users that there are too many visitors and suggest using at off-peak times.
WakingUp
If there is a long period (varies by service, shorter during trial) without service requests, this state may appear when requests resume. In most cases, the next request will be normal, usually within a few seconds.
If this state appears, let the user wait briefly.
ApiTokenExpired
If you use Token to access the service, you also need to handle Token expiration. APIKey access does not require handling this.
Switch MegaBlockTracker¶
MegaTrackerFrameFilter.enabled can control the switch of MegaBlockTracker. After closing, tracking stops and the Block receives a lost signal. If you force display content at this time, you will find the content is stuck to the screen. In the sample, this is implemented through button events.
MegaTrackerFrameFilter also has a switch for cloud service connection (localization). If needed, you can use it according to the interface documentation. Generally, you should not close localization, and disconnecting from the server during use will greatly affect Mega’s performance.