حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لبرنامج Unity الأساسية

تحتوي الأقسام التالية على أوصاف للمفاهيم الأساسية لفهم واستخدام حزمة SDK للخرائط لـ Unity.

فئة ومكوِّن MapsService

تشكّل فئة MapsService نقطة دخول للتفاعل مع حزمة تطوير البرامج (SDK) لتطبيق "خرائط Google" لبرنامج Unity. ينضم إلى هذه الواجهة ApiKey، ويعرض GameObjectManager ودالة LoadMap ، بالإضافة إلى الأحداث من مسار GameObject Creation.

لاستخدام حزمة SDK لخرائط Google في Unity في مشروعك، يمكنك إضافة مكوِّن النص البرمجي لخدمة الخرائط إلى عنصر GameObject فارغ في المشهد. تضيف "خدمة الخرائط" تلقائيًا ميزة "GameObjects" التي تم إنشاؤها للخريطة بصفتها عناصر ثانوية للرابط GameObject هذا. من خلال إرفاق Maps Service (النص البرمجي) مع عنصر GameObject الأساسي، يمكنك الوصول إلى سماته العامة في Unity Inspector—كما هو موضّح هنا.

خدمة الخرائط (نص برمجي)

الميزات الجغرافية في صورة Unity GameObjects

تعرض حزمة تطوير البرامج (SDK) الخاصة بخرائط Google لبرنامج Unity السمات الجغرافية (مثل المباني والطرق والمياه) من قاعدة بيانات "خرائط Google"، مثل Unity GameObjects في الألعاب. في وقت التشغيل، يتم إنشاؤها كعناصر ثانوية لـ GameObject الذي تم إرفاق المكوِّن MapsService بها، وتكون لها أسماء بالنمط {MapFeatureType} ({PlaceID}).

عناصر الألعاب في حزمة تطوير البرامج (SDK)

إنشاء GameObject

أثناء اللعب، تسحب حزمة تطوير البرامج (SDK) البيانات الجغرافية من قاعدة بيانات "خرائط Google" كمربّعات متجهات دلالية (عبر واجهة برمجة تطبيقات Semantic Tile API). فهي تفكّ ترميز هذه البيانات فورًا، وتحوِّلها إلى Unity GameObjects. ويتيح لك هذا الأسلوب الوصول إلى بيانات ميزات الخريطة (كل من البيانات الوصفية والبيانات الهندسية) في أقرب فرصة ممكنة، وذلك حتى تتمكّن من تخصيص GameObjects قبل وصولها إلى نهاية مسار التعلّم.

أول ما تفعله حزمة تطوير البرامج (SDK) لخرائط Google لبرنامج Unity عند تلقّيها بيانات المتجه هو إنشاء كائن MapFeature منها.

في المرحلة المتوسطة في مسار العملية، يتم تخصيص كائنات MapFeature. وهذا يعني أنها تصبح أنواعًا محددة (على سبيل المثال، Google.Maps.Feature.ModeledStructure). تحتوي عناصر MapFeature المتخصصة هذه على MapFeatureShape تفاصيل هندسية ( ModeledVolume في حالة ModeledStructure). تشمل هذه التفاصيل كلاً من البيانات الخاصة بميزة MapFeature (مثل الرؤوس والمثلثات)، والواجهات المشتركة للوصول إلى الحقول المشتركة (مثل المربعات الإحاطة).

يتم تحويل البيانات الهندسية إلى Unity Mesh، وإضافتها إلى GameObject الذي تم إنتاجه من خلال MeshFilter، ثم يتم عرضها مع 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 للقراءة فقط.
  • يتيح لك ضبط Style تخصيص مظهر GameObject الذي تم إنشاؤه.
  • يؤدّي ضبط Prefab إلى استبدال GameObject الذي سيتم إنشاؤه بالإعداد المسبق.

فعاليات 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 أمتار بشكل افتراضي).

إنّ الجمع بين هذه الطرق الثلاث يتيح لحزمة تطوير البرامج (SDK) الخاصة بخرائط Google لبرنامج Unity إنشاء مناظر مدينة مع تباين واقعي يعكس العالم الحقيقي، أو بارتفاع ثابت للمبنى، أو مزيج من الاثنين.

البنى المستندة إلى نموذج

يتم إنشاء البنى المستندة إلى نماذج باستخدام أسلوب وضع النماذج الثلاثي الأبعاد القياسي للمثلثات المتميزة. يستخدم هذا النهج عادةً للمباني التاريخية، مثل تمثال الحرية.

تمثال الحرية النموذجي

تطبيق المواد

في Unity، تستخدم عملية العرض الظلال والمواد والزخارف لإضافة الواقعية إلى GameObjects. تحدد الظلال كيفية تطبيق الزخارف والألوان والإضاءة على الأشكال الهندسية المعروضة، مع تخزين زخارف وألوان معينة وإعدادات أخرى مستخدمة كمادة. يمكنك استخدام مواد لتحديد كيفية عرض السطح — عن طريق تضمين إشارات إلى الزخارف التي تستخدمها ، ومعلومات التجانب ، واللون.

الظلال هي نصوص صغيرة تحتوي على منطق لحساب لون كل بكسل، بناءً على مدخلات الإضاءة وعلى إعداد المواد. تأتي حزمة SDK للخرائط لـ Unity مع أداة تظليل قياسية للهياكل المستندة إلى نماذج، وأداة أخرى لميزات الخريطة الأساسية، ولكنها تدعم أيضًا تطبيق المواد المتقدمة. يتم احتساب إحداثيات تعيين UV لميزة الخرائط GameObjects بطريقة تتيح تطبيق أي مواد أساسية، وستبدو معقولة بدون تعديل.

للحصول على تأثيرات مادية أكثر تقدمًا، توفّر حزمة تطوير البرامج (SDK) للخرائط لـ Unity بيانات إضافية لكل رأس من خلال قنوات UV إضافية، بالإضافة إلى عدد من الوظائف المناسبة لأدوات تظليل cg من خلال مكتبة GoogleMapsShaderLib. يتيح ذلك تنفيذ أشياء مثل شرائح من تسع شرائح لبناء زخارف المباني، مثل قص الزخارف على السطح والأرض وزوايا الجدار والجدران البلاطية.

لمزيد من المعلومات، راجع إنشاء المواد واستخدامها في دليل مستخدم Unity.

قنوات الأشعة فوق البنفسجية

تحتوي قنوات UV لكل نوع MapFeature على بيانات بالنموذج التالي:

ExtrudedStructure

Walls

يتم إنشاء كل جدار على ExtrudedStructure كربعة من النموذج التالي:

Walls

يتم حساب إحداثيات الأشعة فوق البنفسجية للجدران حسب الرباع. لا تتم مشاركة الرؤوس بين الأعمدة الرباعية، للسماح بالعناصر العادية الصلبة بين الجدران (أي السماح لزوايا الجدران بالظهور كزوايا صلبة، بدلاً من حواف مستديرة ناعمة).

القناة 0: (س، ص، عرض، ارتفاع)
x وy هما الإحداثيات بالنسبة إلى الزاوية السفلية اليسرى لهذا المربع (القسم المربع) من الجدار، في حين أنّ العرض والارتفاع هما عرض وارتفاع هذا المربع من الجدار. ينطبق هذا على كل رباعية تشكل الجدار.
سطح بناية

يتوفر في زخارف السقف خيار محاذاة المحور أو محاذاته مع اتجاه ExtrudedStructure. يمكنك ضبط ذلك من خلال كائن ExtrudedStructureStyle.

القناة 0: (س، ص، عرض، ارتفاع)
x وy هما إحداثي كل رأس بالنسبة إلى الزاوية السفلية اليسرى من السقف (على وجه التحديد، زاوية مربع الإحاطة الذي تتم محاذاة محوره الأدنى للسطح). width وheight حجم مربّع إحاطة السطح.

Region

القناة 0: (س، ص، عرض، ارتفاع)
x وy هما إحداثي كل رأس بالنسبة إلى الزاوية السفلية اليسرى لمربّع الإحاطة الذي تتم محاذاته على المحور في المنطقة. تحدّد سمتا width وheight حجم مربع الإحاطة.

Segment

القناة 0: (س، ص، العرض، الطول)
x وy هما إحداثيات كل رأس، ويتم احتسابهما كما لو كان القطاع مستقيمًا تمامًا، بما يسمح بثني الزوايا حول الزوايا. وتحدِّد سمتا العرض والطول أبعاد المقطع.

ModeledStructure

القناة 0:
يتم ضبط كل إحداثي على (0، 0، 0، 0) لأنه ليس هناك حاليًا أي تنفيذ لإحداثيات القوام.

خرائط GoogleShaderLib

تشتمل حزمة تطوير البرامج (SDK) لـ "خرائط Google" لبرنامج Unity على مكتبة تظليل تُعرف باسم GoogleMapsShaderLib لمساعدتك في إنشاء أدوات تظليل تعمل جيدًا مع MapFeature GameObjects. يتم تنفيذ المكتبة في ملف GoogleMapsShaderLib.cginc. يمكنك استخدام المكتبة من خلال تضمين توجيه #include التالي في قسم علامات CGPROGRAM في نص برنامج التظليل.

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

تكون مكتبة التظليل مضمّنة في GoogleMaps.unitypackage. بعد استيراد الحزمة، يمكنك العثور على GoogleMapsShaderLib.cginc داخل مجلد المشروع /Assets/GoogleMaps/Materials/.

تسعة شرائح

يتضمن GoogleMapsShaderLib وظيفة مناسبة يمكنك استخدامها في أدوات تظليل الأجزاء لتوفير تسعة شرائح من الزخارف. تسعة أجزاء هي تقنية لتغطية الأسطح بزخرفة، حيث يتم تقسيم الهيئة إلى تسعة أجزاء باستخدام سلسلة من الحدود. يتم تجانب المناطق بين الحدود، وتظل المناطق خارج الحدود ثابتة - كما هو موضح هنا:

تسعة شرائح

على سبيل المثال، عند تطبيق زخارف مكونة من تسع شرائح على جدار أحد المباني، يتم تطبيق الجزء العلوي من الزخرفة على الجزء العلوي من الجدار (أسفل السقف مباشرةً)، ويتم تطبيق الجزء السفلي من الزخرفة على الجزء السفلي من الجدار (متصلاً بالأرض)، ويتم تطبيق جوانب الزخرفة على حواف الجدار، ويتم تقسيم المنطقة الموجودة في وسط الزخرفة بالتساوي عبر الزخرفة.

في الطرق (على سبيل المثال آخر)، تسمح لك الأجزاء التسعة برصيف ذات عرض ثابت، ولكن بعدد متغير من الممرات، بناءً على عرض الطريق.

يمكنك استخدام تسعة تقطيع من خلال تضمين GoogleMapsShaderLib.cginc في التظليل"، ثم استدعاء الدالة nineSlice. يتم تضمين نماذج التظليل والمواد في GoogleMaps.unitypackage لتوضيح كيف يمكنك استخدام الدالة nineSlice لإنشاء ناطحة سحاب واقعية ذات حجم متغير، بدون تمديد أو تمزيق.

مثال على موقع المواد
/Assets/GoogleMaps/Examples/04_Advanced/MoreStyling/Materials/NineSlicing
مثال على موقع Shader
/Assets/GoogleMaps/Examples/04_Advanced/MoreStyling/Materials/NineSlicing/BuildingWall.shader

يمكنك استخدام تسعة شرائح على أي MapFeature، باستثناء ModeledStructures، التي لا تحتوي حاليًا على أي إحداثيات.

نظام الإحداثيات

تستخدم حزمة تطوير البرامج (SDK) لـ "خرائط Google" لنظام إحداثيات Unity توقّع Web Mercator للتحويل بين خطوط الطول والعرض في تنسيق كروي WGS 84 وخط الطول والعرض في Unity Worldspace الديكارتي (Vector3).

ترتبط قيم Vector3 بالأصل العائم، والذي يتم تعيينه عادةً على موقع البداية للمستخدم. ونتيجةً لذلك، يجب عدم الاحتفاظ بقيم Vector3 خارج الجلسة (أي على الخادم أو على جهاز المستخدم). ننصحك بتحديد المواقع الجغرافية الفعلية للعالم باستخدام أزواج من خطوط الطول والعرض.

يتم استخدام مصدر عائم لتجنب مشاكل ثبات النقطة العائمة. تستخدم فئة Vector3 في Unity أرقام النقاط العائمة أحادية الدقة، وتقل كثافة أرقام النقاط العائمة القابلة للتمثيل مع زيادة المقدار (أي أن أرقام النقاط العائمة الأكبر تصبح أقل دقة). يمكنك تعديل المصدر العائم عندما يبتعد المستخدمون عن المصدر بحيث تحوّل هذا الأمر إلى مشكلة. يمكنك ضبطها على قيمة صغيرة نسبيًا (على سبيل المثال، 100 أو 200 متر)، أو أكبر (أكبر من 1 كيلومتر) بناءً على عدد المرات التي تريد فيها إجراء التحديث.

يتم تغيير نطاق Unity Worldspace إلى 1:1 (متر)، استنادًا إلى خط العرض الأولي للمصدر. في توقّع ماركاتور، يختلف المقياس قليلاً حسب خط العرض، لذا ينحرف مقياس Unity Wordspace قليلاً عن 1:1 عندما يتحرك المستخدمون شمالاً وجنوبًا، ومع ذلك، من غير المتوقع أن يتحرك المستخدمون بعيدًا (أو بسرعة) بما يكفي ليكون ملحوظًا.

تحتوي حزمة تطوير البرامج (SDK) في "خرائط Google" لبرنامج Unity على دوال الإحالات الناجحة لإجراء الإحالات الناجحة بين Google.Maps.LatLng وUnity Worldspace (Vector3) التي تأخذ في الاعتبار المصدر العائم والمقياس.

تحميل الأخطاء

يمكن التعامل مع الأخطاء التي تحدث أثناء تحميل بيانات الخريطة من الشبكة باستخدام حدث MapLoadErrorEvent. تعالج حزمة تطوير البرامج (SDK) للخرائط الخاصة بـ Unity معظم أنواع الأخطاء نفسها إذا لم تُضف معالج أحداث. ومع ذلك، هناك خطأ يتطلب أن يتخذ تطبيقك بعض الإجراءات. يتم تحديد ذلك من خلال MapLoadErrorArgs.DetailedErrorCode ووصفه أدناه.

UnsupportedClientVersion

لم يعد هذا الإصدار من حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لـ Unity متاحًا، وقد يكون ذلك بالاقتران مع مفتاح واجهة برمجة التطبيقات الحالي. يجب أن يطلب تطبيقك عادةً من المستخدم التحديث إلى إصدار أحدث من التطبيق.

يعني هذا الخطأ عادةً أنّ إصدار حزمة تطوير البرامج (SDK) للخرائط لـ Unity قديم جدًا. في حالات نادرة، قد نستخدم هذا إذا اكتشفنا مشكلة حرجة في إصدار SDK للخرائط لـ Unity أو بمفتاح واجهة برمجة تطبيقات. سنبذل قصارى جهدنا لإبلاغه بهذا الأمر والتأكد من عدم حدوث ذلك حتى تتوفر نسخة صالحة من التطبيق متاحة للتحديث.

من أفضل الممارسات التأكّد من توفّر مسار ترقية مناسب لتطبيقك في حال حدوث هذا الخطأ، ما يسمح للمستخدمين بالانتقال إلى إصدار أحدث من تطبيقك باستخدام إصدار متوافق من حزمة تطوير البرامج (SDK). لمزيد من المعلومات، راجِع مستندات مفتاح إيقاف العميل.

المشاكل المعروفة

يتمّ عرض ميزات الخريطة الأساسية من الخلف بدون اختبار z لأنّ جميع الميزات من هذا النوع يتمّ عرضها في المستوى نفسه. يجب ضبط اختبار z على ZTest دائمًا على أي مواد بديلة تطبّقها على ميزات الخريطة الأساسية لضمان عرض هذه المواد بشكل صحيح.

أدرجنا Google في عيّنة من أداة تظليل البيانات تعالج هذه المشاكل في GoogleMaps.unitypackage. يُطلق عليه "BaseMapTextured.shader، وهو موجود في مجلد /Assets/GoogleMaps/Materials/. لاستخدام الأداة على إحدى المواد، حدد Google > الخرائط > Shaders > Basemap Textured من القائمة المنسدلة لأداة التظليل في عارض المواد.

عند تصميم كائن Feature.Region أو Feature.AreaWater، يمكنك تطبيق تعبئة باستخدام مادة أو لون مخصّص أو لون يتم إنشاؤه تلقائيًا ويتم اختياره من خلال تعداد FillModeType داخل كائن النمط. Auto يتم إنشاء الألوان استنادًا إلى قيمة نوع استخدام "المنطقة".