Maps SDK برای مفاهیم کلیدی Unity

بخش‌های زیر حاوی توضیحاتی درباره مفاهیم کلیدی برای درک و استفاده از Maps SDK for Unity است.

کلاس و مؤلفه MapsService

کلاس MapsService به عنوان نقطه ورودی برای تعامل با Maps SDK for Unity عمل می کند. ApiKey را محصور می کند و GameObjectManager و تابع LoadMap و همچنین رویدادهایی از خط لوله ایجاد GameObject را نشان می دهد.

برای استفاده از Maps SDK for Unity در پروژه یونیتی خود، مولفه اسکریپت Map Service را به یک GameObject خالی در صحنه خود اضافه می کنید. خدمات نقشه به طور خودکار ویژگی نقشه تولید شده GameObject را به عنوان فرزندان این لنگر GameObject اضافه می کند. با استفاده از Maps Service (اسکریپت) متصل به GameObject پایه خود، می‌توانید به ویژگی‌های عمومی آن در Unity Inspector دسترسی داشته باشید - همانطور که در اینجا نشان داده شده است.

ویژگی های جغرافیایی به عنوان Unity GameObjects

Maps SDK for Unity ویژگی‌های جغرافیایی (مانند ساختمان، جاده‌ها و آب) را از پایگاه داده Google Maps به عنوان Unity GameObjects در بازی‌ها ارائه می‌کند. در زمان اجرا، آنها به عنوان فرزندان GameObject ایجاد می شوند که مؤلفه MapsService به آن متصل است و نام هایی به شکل {MapFeatureType} ({PlaceID}) دارند.

بازی ایجاد شی

در طول گیم پلی، SDK داده های جغرافیایی را از پایگاه داده نقشه های گوگل به عنوان کاشی های برداری معنایی (از طریق Semantic Tile API) پایین می آورد. این داده ها را در لحظه رمزگشایی می کند و آن را به Unity GameObjects تبدیل می کند. این رویکرد به شما امکان می‌دهد در اولین فرصت به داده‌های ویژگی نقشه (هم ابرداده و هم داده‌های هندسی) دسترسی داشته باشید، بنابراین می‌توانید GameObjects را قبل از رسیدن به انتهای خط لوله سفارشی کنید.

اولین کاری که Maps SDK for Unity هنگام دریافت داده های برداری انجام می دهد، ساختن یک شی MapFeature از آن است.

در یک مرحله میانی در خط لوله، اشیاء MapFeature تخصصی هستند. یعنی تبدیل به انواع خاصی می شوند (مثلاً Google.Maps.Feature.ModeledStructure ). این اشیاء تخصصی MapFeature حاوی جزئیات هندسی MapFeatureShape هستند ( ModeledVolume در مورد ModeledStructure ). این جزئیات شامل داده‌های مخصوص MapFeature (مانند رئوس و مثلث‌ها) و رابط‌های مشترک برای دسترسی به فیلدهای مشترک (مانند جعبه‌های محدود) می‌شود.

داده های هندسه به یک Unity Mesh تبدیل می شوند و از طریق MeshFilter به GameObject ایجاد شده اضافه می شوند و سپس با MeshRenderer نمایش داده می شوند.

دسترسی به خط لوله

MapFeature ها از طریق رویدادهایی که در مراحل مختلف خط لوله ایجاد می شوند در معرض دید شما قرار می گیرند. اینها شامل رویدادهای WillCreate می‌شوند که درست قبل از ایجاد GameObject فعال می‌شوند و به شما امکان می‌دهند گزینه‌های استایل را مشخص کنید، یا حتی ایجاد را لغو کنید. و رویدادهای DidCreate دقیقا پس از ایجاد GameObject فعال می شوند و به شما امکان می دهند اضافات یا تغییراتی در مش تمام شده ایجاد کنید.

به عنوان مثال، می‌توانید ExtrudedStructures پس از آتش‌سوزی WillCreateExtrudedStructureEvent بررسی کنید و تمام ساختمان‌های کوتاه‌تر از 20 متر را پنهان کنید (یا می‌توانید از ایجاد آن‌ها به کلی صرفنظر کنید).

انواع رویدادها

فضای نام Google.Maps.Event شامل یک کلاس رویداد برای هر نوع ویژگی جغرافیایی است.

• رویدادهای بخش ها
• رویدادهای مناطق
• رویدادهای آب خط
• رویدادهای آب منطقه
• رویدادهای سازه های اکسترود شده
• رویدادهای ساختارهای مدل شده

هر یک از این انواع رویداد دارای یک شیء رویداد عضو عمومی WillCreate و DidCreate است که می توانید در آن مشترک شوید، همانطور که در مثال کد زیر نشان داده شده است.

dynamicMapsService.MapsService.Events.ExtrudedStructureEvents.DidCreate.AddListener(args => {

    // Apply nine-sliced walls and roof materials to this building.
    buildingTexturer.AssignNineSlicedMaterials(args.GameObject);

    // Add a border around the building base using the Building Border Builder class,
    // coloring it using the given border Material.
    Extruder.AddBuildingBorder(args.GameObject, args.MapFeature.Shape, BuildingAndRoadBorder);
});

رویدادها WillCreate

رویدادهای WillCreate بلافاصله پس از ایجاد MapFeature اجرا می‌شوند، اما قبل از اینکه GameObject نهایی از آن تولید شود. رویدادهای WillCreate به شما این امکان را می دهد که GameObjects ایجاد شده از MapFeature را سرکوب یا سفارشی کنید. آرگومان های رویداد WillCreate به شکل زیر هستند:

using System.ComponentModel;
using Google.Maps.Decoded;
using UnityEngine;

namespace Google.Maps {
  public class WillCreateGameObjectEventArgs<T, U>
      : CancelEventArgs where T : IMapObject, U : IGameObjectStyle {

    public readonly T MapObject;
    public U Style;
    public GameObject Prefab;

    Public WillCreateGameObjectEventArgs(T mapObject, U defaultStyle, GameObject prefab) {
      MapObject = mapObject;
      Style = defaultStyle;
      Prefab = prefab;
    }
  }
}

• تنظیم Cancel (به ارث رسیده از CancelEventArgs ) روی true ، ایجاد GameObject را سرکوب می کند.
• MapObject فقط خواندنی است.
• Setting Style به شما امکان می دهد ظاهر GameObject ایجاد شده را سفارشی کنید.
• Setting Prefab جایگزین GameObjectی می شود که تولید می شد، با prefab.

رویدادهای DidCreate

رویدادهای DidCreate پس از تولید GameObject و پس از اضافه شدن آن به صحنه اجرا می شوند. زمانی که ایجاد GameObject موفقیت آمیز بود به شما اطلاع می دهند و به شما امکان می دهند پردازش بیشتری را انجام دهید. آرگومان های رویداد DidCreate شکل زیر را دارند:

using System.ComponentModel;
using Google.Maps.Decoded;
using UnityEngine;

namespace Google.Maps {
  public class DidCreateGameObjectEventArgs<T, U>
      : EventArgs where T : IMapObject, U : IGameObjectStyle {

    public readonly T MapObject;
    public GameObject CreatedObject;

    Public DidCreateGameObjectEventArgs(T mapObject, GameObject createdObject) {
      MapObject = mapObject;
      CreatedObject = createdObject;
    }
  }
}

• MapObject فقط خواندنی است - بنابراین جهش آن هیچ تغییری در صحنه ایجاد نمی کند.
• تغییر CreatedObject باعث تغییر GameObject اضافه شده به صحنه می شود .

ساختمان ها

دو نوع ساختمان وجود دارد: ساختمان های اکسترود شده و سازه های مدل شده.

ساختمان های اکسترود شده

ساختمان های اکسترود شده از یک طرح کلی (یعنی یک ردپای دو بعدی) و یک ارتفاع ایجاد می شوند. SDK بیشتر ساختمان ها را به این صورت نشان می دهد و آنها را به سه روش زیر تولید می کند:

• استفاده از داده های واقعی ارتفاع (جایی که این اطلاعات در دسترس است). این رفتار به طور پیش فرض است.

• با ارائه یک ارتفاع ثابت برای همه ساختمان ها، بدون توجه به ارتفاع واقعی آنها.

• با ارائه ارتفاع پشتیبان برای تمام ساختمان هایی که ارتفاع واقعی ندارند (به طور پیش فرض، این مقدار روی 10 متر تنظیم شده است).

ترکیب این سه روش به Maps SDK for Unity اجازه می‌دهد تا مناظر شهری با واریانس واقعی منعکس‌کننده دنیای واقعی، یا با ارتفاع ساختمان ثابت، یا ترکیبی از این دو ایجاد کند.

سازه های مدل سازی شده

ساختارهای مدل‌سازی شده با استفاده از رویکرد مدل‌سازی سه بعدی استاندارد مثلث‌های تسلیتی تولید می‌شوند. این رویکرد معمولاً برای ساختمان های شاخص مانند مجسمه آزادی استفاده می شود.

استفاده از مواد

در یونیتی، فرآیند رندر از سایه‌زن‌ها ، متریال‌ها و بافت‌ها استفاده می‌کند تا واقع‌گرایی را به GameObjects اضافه کند. سایه‌زن‌ها نحوه اعمال بافت‌ها، رنگ‌ها و نور را برای هندسه نمایش‌داده‌شده با بافت‌ها، رنگ‌ها و سایر تنظیماتی که به‌عنوان ماده ذخیره می‌شوند، تعریف می‌کنند. شما از مواد برای تعریف نحوه رندر شدن یک سطح استفاده می کنید - با ذکر ارجاع به بافت هایی که استفاده می کند، اطلاعات کاشی کاری و رنگ.

سایه بان ها اسکریپت های کوچکی هستند که منطق محاسبه رنگ هر پیکسل را بر اساس ورودی نور و پیکربندی متریال دارند. Maps SDK for Unity با یک سایه زن استاندارد برای ساختارهای مدل‌سازی شده و دیگری برای ویژگی‌های نقشه پایه ارائه می‌شود، اما از برنامه‌های متریال پیشرفته نیز پشتیبانی می‌کند. مختصات نقشه برداری اشعه ماوراء بنفش برای ویژگی های نقشه GameObjects به گونه ای محاسبه می شود که می توان از هر ماده اولیه استفاده کرد و بدون تغییر منطقی به نظر می رسد.

برای جلوه‌های متریال پیشرفته‌تر، Maps SDK for Unity داده‌های اضافی را در هر رأس از طریق کانال‌های UV اضافی و همچنین تعدادی عملکرد راحت برای سایه‌زن‌های cg از طریق کتابخانه GoogleMapsShaderLib فراهم می‌کند. این به مواردی مانند بافت‌های ساختمانی Nine-Sliced ​​اجازه می‌دهد - برش بافت در سقف، زمین، گوشه‌های دیوار و دیوارهای کاشی‌شده برای یک ساختمان.

برای اطلاعات بیشتر، به ایجاد و استفاده از مواد در راهنمای کاربر Unity مراجعه کنید.

کانال های UV

کانال های UV برای هر نوع MapFeature حاوی داده هایی به شکل زیر است:

ExtrudedStructure

دیوارها

هر دیوار در یک ExtrudedStructure به صورت چهارتایی به شکل زیر ساخته می شود:

مختصات اشعه ماوراء بنفش برای دیوارها در هر چهار عدد محاسبه می شود. رئوس ها بین چهارتایی مشترک نیستند - تا نرمال های سخت بین دیوارها ایجاد شود (یعنی اجازه دهید گوشه های دیوارها به جای لبه های گرد نرم به صورت زوایای سخت ظاهر شوند).

کانال 0: (x، y، عرض، ارتفاع)

x و y مختصات نسبت به گوشه سمت چپ پایین این چهار (بخش مربع) دیوار هستند، در حالی که عرض و ارتفاع عرض و ارتفاع این چهار دیواری هستند. این در مورد هر چهارتایی که دیوار را می سازد صدق می کند.

سقف

بافت های سقف این گزینه را دارند که هم تراز محوری باشند یا هم تراز با جهت ExtrudedStructure . شما این را از طریق شی ExtrudedStructureStyle تنظیم می کنید.

کانال 0: (x، y، عرض، ارتفاع)

x و y مختصات هر رأس، نسبت به گوشه پایین سمت چپ سقف هستند (به طور خاص، گوشه جعبه مرزی هم تراز با محور حداقل پوشش برای سقف). عرض و ارتفاع اندازه جعبه مرزی سقف را مشخص می کند.

Region

کانال 0: (x، y، عرض، ارتفاع)

x و y مختصات هر رأس نسبت به گوشه پایین سمت چپ کادر مرزی هم تراز با محور برای منطقه هستند. عرض و ارتفاع اندازه جعبه مرزی را مشخص می کند.

Segment

کانال 0: (x، y، عرض، طول)

x و y مختصات هر رأس هستند که به گونه‌ای محاسبه می‌شوند که گویی قطعه کاملاً مستقیم است - تا بافت‌سازی بتواند در گوشه‌ها خم شود. عرض و طول ابعاد قطعه را مشخص می کند.

ModeledStructure

کانال 0:

هر مختصات روی (0، 0، 0، 0) تنظیم می شود زیرا در حال حاضر هیچ پیاده سازی مختصات بافتی وجود ندارد.

GoogleMapsShaderLib

Maps SDK for Unity شامل یک کتابخانه سایه‌زن به نام GoogleMapsShaderLib است که به شما کمک می‌کند سایه‌بان‌هایی بسازید که به خوبی با MapFeature GameObjects کار کنند. این کتابخانه در فایل GoogleMapsShaderLib.cginc پیاده سازی شده است. می‌توانید با قرار دادن دستور #include زیر در بخش پرچم‌های CGPROGRAM در اسکریپت سایه‌زنتان از کتابخانه استفاده کنید.

CGPROGRAM
// ...
#include "/Assets/GoogleMaps/Materials/GoogleMapsShaderLib.cginc"
// ...
ENDCG

کتابخانه سایه‌زن در داخل GoogleMaps.unitypackage قرار گرفته است. پس از وارد کردن بسته، می توانید GoogleMapsShaderLib.cginc را در پوشه پروژه /Assets/GoogleMaps/Materials/ پیدا کنید.

نه برش

GoogleMapsShaderLib شامل یک تابع راحت است که می توانید از آن در سایه زن های قطعه برای ارائه 9 برش بافت استفاده کنید. نه برش تکنیکی برای پوشاندن سطوح با بافت است که در آن بافت با استفاده از یک سری کران به 9 قسمت تقسیم می شود. نواحی بین مرزها کاشی کاری شده اند و نواحی خارج از محدوده ثابت می مانند - همانطور که در اینجا نشان داده شده است:

به عنوان مثال، هنگام اعمال یک بافت نه برش به دیوار یک ساختمان، قسمت بالای بافت به بالای دیوار (درست زیر سقف)، پایین بافت به پایین دیوار (متصل شده) اعمال می شود. به زمین)، کناره های بافت روی لبه های دیوار اعمال می شود و ناحیه وسط بافت به طور یکنواخت در سراسر دیوار کاشی می شود.

در جاده ها (برای مثال دیگر)، نه برش به شما امکان می دهد یک پیاده رو با عرض ثابت، اما با تعداد خطوط متغیر، بسته به عرض جاده داشته باشید.

می‌توانید با قرار دادن GoogleMapsShaderLib.cginc در سایه‌زن خود، و سپس فراخوانی تابع nineSlice نه برش استفاده کنید. سایه‌زن‌ها و متریال‌های نمونه در بسته‌بندی GoogleMaps.unity گنجانده شده‌اند تا نشان دهند چگونه می‌توانید از تابع nineSlice برای ایجاد یک آسمان‌خراش واقعی با اندازه متغیر-بدون کشش یا پاره شدن استفاده کنید.

نمونه مکان مواد

/Assets/GoogleMaps/Examples/04_Advanced/MoreStyling/Materials/NineSlicing

مثال مکان سایه بان

/Assets/GoogleMaps/Examples/04_Advanced/MoreStyling/Materials/NineSlicing/BuildingWall.shader

شما می توانید از نه برش بر روی هر MapFeature استفاده کنید، به جز ModeledStructures ، که در حال حاضر هیچ مختصات بافتی ندارند.

سیستم مختصات

سیستم مختصات Maps SDK for Unity از Web Mercator Projection برای تبدیل بین WGS 84 عرض-طول جغرافیایی کروی و Unity Worldspace ( Vector3 ) استفاده می کند.

مقادیر Vector3 نسبت به یک مبدا شناور است که معمولاً روی مکان شروع کاربر تنظیم می شود. در نتیجه، شما نباید مقادیر Vector3 را خارج از یک جلسه (یعنی در سرور خود یا در دستگاه کاربر) حفظ کنید. توصیه می‌کنیم مکان‌های دنیای فیزیکی را با استفاده از جفت‌های طول و عرض جغرافیایی مشخص کنید.

یک مبدا شناور برای جلوگیری از مشکلات پایداری ممیز شناور استفاده می شود. کلاس Vector3 Unity از اعداد ممیز شناور تک دقیق استفاده می کند و چگالی اعداد ممیز شناور قابل نمایش با افزایش بزرگی آنها کاهش می یابد (به این معنی که اعداد ممیز شناور بزرگتر دقیق تر می شوند). هر زمان که کاربران به اندازه کافی از مبدأ فاصله گرفتند، می‌توانید مبدا شناور را به‌روزرسانی کنید. می توانید این مقدار را روی مقدار نسبتاً کوچکی (مثلاً 100 یا 200 متر) یا بزرگتر (بیشتر از 1 کیلومتر) تنظیم کنید، بسته به اینکه هر چند وقت یکبار می خواهید چیزها را به روز کنید.

Unity Worldspace بر اساس عرض جغرافیایی مبدا اولیه به 1:1 (متر) مقیاس بندی شده است. در Mercator Projection، مقیاس بر اساس عرض جغرافیایی کمی متفاوت است، بنابراین مقیاس Unity Wordspace به طور جزئی از 1:1 با حرکت کاربران به شمال و جنوب متفاوت است. با این حال، انتظار نمی رود کاربران به اندازه کافی دور (یا سریع) حرکت کنند تا این امر قابل توجه باشد.

Maps SDK for Unity حاوی توابع تبدیلی برای تبدیل بین Google.Maps.LatLng و Unity Worldspace (Vector3) است - که مبدا و مقیاس شناور را در نظر می‌گیرد.

خطاهای بارگذاری

خطاهایی که هنگام بارگیری داده های نقشه از شبکه رخ می دهند را می توان با رویداد MapLoadErrorEvent کنترل کرد. اگر یک کنترل کننده رویداد اضافه نکنید، Maps SDK for Unity خودش اکثر انواع خطاها را کنترل می کند. با این حال، خطایی وجود دارد که لازم است برنامه شما اقداماتی انجام دهد. این توسط MapLoadErrorArgs.DetailedErrorCode مشخص شده و در زیر توضیح داده شده است.

UnsupportedClientVersion

این نسخه از Maps SDK for Unity دیگر پشتیبانی نمی‌شود، احتمالاً در ترکیب با کلید API فعلی. معمولاً برنامه شما باید از کاربر بخواهد که به نسخه جدیدتر برنامه شما به روز شود.

این خطا معمولاً به این معنی است که Maps SDK برای نسخه Unity خیلی قدیمی است. در موارد نادر، اگر مشکلی مهم در نسخه‌ای از Maps SDK for Unity یا با یک کلید API کشف کنیم، ممکن است از آن استفاده کنیم. ما تمام تلاش خود را برای برقراری ارتباط با این موضوع انجام خواهیم داد و اطمینان حاصل خواهیم کرد که تا زمانی که یک نسخه کاربردی از برنامه برای به‌روزرسانی در دسترس نباشد، این اتفاق نمی‌افتد.

بهترین کار این است که در صورت بروز این خطا، مطمئن شوید که برنامه شما مسیر ارتقای مناسبی دارد و به کاربران شما امکان می‌دهد به نسخه جدیدتر برنامه شما با نسخه SDK پشتیبانی شده مهاجرت کنند. برای اطلاعات بیشتر، به مستندات Client Kill Switch مراجعه کنید.

مشکلات شناخته شده

ویژگی های نقشه پایه بدون تست z به صورت پشت به جلو رندر می شوند زیرا همه ویژگی های این نوع در یک صفحه نمایش داده می شوند. شما باید z-testing را روی ZTest Always روی مواد جایگزینی که برای ویژگی های نقشه پایه اعمال می کنید، تنظیم کنید تا مطمئن شوید که آنها به درستی رندر شده اند.

Google یک سایه‌زن نمونه قرار داده است که به این مشکلات رسیدگی می‌کند—در GoogleMaps.unitypackage . "BaseMapTextured.shader نامیده می شود و در پوشه /Assets/GoogleMaps/Materials/ قرار دارد. برای استفاده از آن بر روی یک ماده، Google > Maps > Shaders > BaseMap Textured را از منوی کشویی shader در بازرس مواد انتخاب کنید.

هنگام استایل دادن به یک شی Feature.Region یا Feature.AreaWater ، می‌توانید با استفاده از یک ماده، یک رنگ سفارشی، یا یک رنگ تولید شده به‌طور خودکار که از طریق فهرست FillModeType در شیء استایل‌سازی انتخاب شده است، یک پرکننده اعمال کنید. رنگ‌های Auto بر اساس مقدار نوع استفاده منطقه تولید می‌شوند.